🧯
実行時のエラー対応
この記事では、レシピの実行が「失敗」になったときや、思ったとおりに取り込めなかったときの原因の調べ方と、よくある原因ごとの対処を説明します。
実行時のエラーは、ソースの取得 → 変換 → ロード（書き込み）のどのフェーズで止まったかを先に切り分けると、確認すべき設定を絞り込めます。
前提
Step 1 失敗した実行の詳細を開く
Step 2 「ログ」タブで失敗したフェーズを切り分ける
Step 3 「概要」タブでエラーの内容を確認する ・エラーの内容の確認方法
Step 4 「外部通信」タブで外部システムとのやり取りを確認する ・取り込み（インポート）で失敗したとき
よくある失敗原因と対処
Step 2 「ログ」タブで失敗したフェーズを切り分ける
Step 3 「概要」タブでエラーの内容を確認する ・エラーの内容の確認方法
Step 4 「外部通信」タブで外部システムとのやり取りを確認する ・取り込み（インポート）で失敗したとき
よくある失敗原因と対処
Step 1 失敗した実行の詳細を開く
- サイドメニューの「実行履歴」、またはレシピ詳細の「実行履歴」タブをクリック
- 一覧の「結果」列が「失敗」になっている実行をクリック 「結果」は「成功」「失敗」「実行中」「待機中」「キャンセル」のいずれかで表示されます。
取り込み（インポート）の書き込みで失敗した実行は、「結果」が「成功」のまま残ります。
この場合は、実行詳細の「概要」タブの「統計」で、「読込行数」が0、「エラー行数」に件数が入る形で現れます。取り込みのレシピを実行したあとは、「結果」だけでなく「読込行数」と「エラー行数」もあわせてご確認ください。
実行詳細画面には「概要」「ログ」「外部通信」「レコード」のタブがあり、ファイルを入力または出力した実行ではさらに「データ」タブが表示されます。原因を調べるときは、まず「ログ」タブでどのフェーズまで進んだかを確認し、そのうえで「概要」「外部通信」「レコード」で内容を詰めます。
Step 2 「ログ」タブで失敗したフェーズを切り分ける
「ログ」タブの「実行ログ」には、「タイムスタンプ」「レベル」「フェーズ」「メッセージ」の4列が時系列で並びます。「フェーズ」を上から追うと、ソースの取得・変換・ロード（書き込み）のどこまで進んで、どこで止まったかが分かります。これが原因調査の起点になります。
- 「レベル」を見て、 の行を探します レベルは の4種類です。
- その行の「フェーズ」を見て、どの処理で止まったかを確認します
- 直前の「メッセージ」までは処理が進んでいるため、止まった位置の設定から見直します
「フェーズ」は英字のまま表示されます。表示される値と、そこで失敗したときに疑うところは以下の通りです。
| フェーズ | 処理 | そこで失敗したときに疑うこと |
|---|---|---|
| 実行の開始 | 実行が始まった記録です。ここで止まっている場合は、レシピが参照している設定を読み込めていない可能性があります | |
| ソースの取得 | 接続設定の認証情報、ソースの URL やパス、アップロードしたファイルの中身、外部システム側の仕様変更 | |
| 変換 | 変換のマッピング、変換ルールの設定、ソース側の列名の変更 | |
| ロード（書き込み） | 取り込み先で必須になっている属性、マスタに存在しない値、インポート設定、ターゲットの出力先 | |
| 実行の終了 | 実行の終了の記録です。ここに「ジョブ失敗」が記録されている場合、原因はその前のフェーズにあります |
の「変換フェーズ完了」には、変換できた行数（）、警告のあった行数（）、エラーになった行数（）が記録されます。
この行が出ていて、そのあとの で になっている場合は、変換までは成功していて、ロード（書き込み）で失敗している状態です。ソースや変換ではなく、取り込み先の設定と、実際に送っている値を確認してください。
Step 3 「概要」タブでエラーの内容を確認する
「概要」タブは「基本情報」「日時」「統計」「実行オプション」に分かれています。「統計」には「抽出行数」「読込行数」「エラー行数」が並び、実行そのものを止めたエラーが記録されている場合にだけ、いちばん下に「エラー」が表示されます。ここで、全体が止まっているのか、行の単位で失敗しているのかを見分けます。
- 「エラー」が表示されている場合は、実行そのものが途中で止まっています。内容の読み方は次の項をご覧ください
- 「抽出行数」が0の場合は、ソースからデータを取得できていません。Step 4 の「外部通信」タブを確認します
- 「エラー行数」だけが出ている場合は、行の単位で失敗しています。「レコード」タブで該当する行を確認します
- 「読込行数」が0で、「エラー行数」が「抽出行数」と同じ場合は、取り込み先への書き込みがまとめて失敗しています。Step 4 の「外部通信」タブを確認します
「レコード」タブの「行ライフサイクル記録」では、1行ごとに「生入力」「解釈」「変換」「出力」の4段階を追えます。
どの段階で値が意図と違っているかを見れば、ソース側のデータの問題か、変換の設定の問題かを切り分けられます。失敗した行には 、問題のない行には が表示されます。
エラーの内容の確認方法
エラーの内容は、「概要」タブの「エラー」のほか、「ログ」タブの の行の「メッセージ」、「外部通信」タブのカードの「エラー」にも表示されます。いずれもシステムが受け取った内容がそのままの形で表示され、日本語に整形された説明ではないため、以下を拾って読みます。
- 取り込み（ロード）の検証で失敗した場合は、先頭が で始まり、そのあとに失敗した内容が1件ずつ続きます
- で始まる行が続けて並びますが、これはプログラム内部の記録です。読み飛ばして、その手前の1行だけを読みます
- … 送信したデータの何件目で失敗したか 先頭のデータが です。ヘッダー行は数えません。
- … どの属性で失敗したか 属性のラベルが言語ごとに表示されます。
- … その属性に対応する列
- 必須の属性に値が入っていない場合は、 を含む内容になります この語の手前に出るのは属性の内部 ID です。日本語の属性名は の側をご覧ください。
内容が長い場合は、まず と の組み合わせだけを拾ってください。
「どの行の、どの属性で失敗したか」が分かれば、変換のマッピングを直すのか、元データを直すのかを判断できます。
Step 4 「外部通信」タブで外部システムとのやり取りを確認する
「外部通信」タブでは、実行中に行われたやり取りを1件ごとにカードで確認できます。カードの先頭には「HTTP 通信」「ファイル I/O」「インポート (Inbound LOAD)」「取得 (Outbound EXTRACT)」のいずれかの種別と、そのやり取りが行われたフェーズが表示されます。
- 「HTTP 通信」のカードで、「ステータス」と「レスポンスボディ」を確認します
- 応答が認証のエラーになっている場合は、接続設定の認証情報を確認します
- 応答の内容が想定と違う場合は、「メソッド」「URL」「リクエストボディ」を見て、外部システム側の仕様が変わっていないかを確認します
取り込み（インポート）で失敗したとき
取り込みのレシピでは、「インポート (Inbound LOAD)」のカードが記録されます。ロード（書き込み）で失敗した原因は、ここで確認できます。
- 「成否」が「失敗」になっているカードを探します
- 「エラー」に、取り込み先から返されたエラーの内容が表示されます
- 「ペイロード」に、実際に送信した値が先頭5行分、 の形で表示されます 必須の属性が空になっていないか、値がマスタと合っているかを、ここで実物を見て確認できます。
記録が1件もない実行では、「外部通信記録がありません。」と表示されます。
よくある失敗原因と対処
実行時に失敗する原因は、次のいずれかであることが多いです。
| 原因 | 確認する場所 | 対処 |
|---|---|---|
| 取り込み先で必須になっている属性に値が入っていない 例）メールアドレス | 「ログ」タブ（） 「外部通信」タブの「エラー」と「ペイロード」 | 変換のマッピングで、その属性に値が入るように設定します。値を渡さない運用にする場合は、ディレクトリサービス側でその属性の必須設定を見直します |
| マスタに存在しない値を渡している 例）存在しない会社コード | 「ログ」タブ（） 「外部通信」タブの「エラー」と「ペイロード」 | 元データの値をマスタに合わせて修正するか、変換ルールでマスタの値に変換します。その値自体が正しい場合は、ディレクトリサービス側にマスタとして登録します |
| 接続設定の認証情報が期限切れになっている | 「外部通信」タブ | 接続設定の認証情報を最新のものに更新し、保存・デプロイしてから再実行します |
| 外部システム側の API の仕様が変わった | 「外部通信」タブ 「ログ」タブ | 変更後の仕様に合わせて、ソースまたはターゲットの設定を見直します |
| 取り込むデータの内容が設定と合っていない | 「概要」タブの「統計」＞「エラー行数」 「レコード」タブ | 元データを修正するか、その形式を受け付けられるように変換ルールを見直します |
| 参照している接続設定が削除・変更された | 「ログ」タブ 「外部通信」タブ | 接続設定を選び直すか、削除された接続設定を作り直して、保存・デプロイします |
| 参照しているインポート設定が削除・変更された | 「ログ」タブ | ターゲットの設定を見直し、保存・デプロイします |
取り込み先で必須になっている属性の値が空であることは、デプロイ時には検出されません。
デプロイの整合性チェックは、レシピの設定そのもの（参照先の接続設定やインポート設定が存在するか、マッピングが空になっていないかなど）を確認するもので、取り込み先で必須になっている属性に実際に値が入るかどうかまでは確認しません。
そのため、デプロイは通るのに実行で取り込めない、という形で現れます。マスタに存在しない値（例：存在しない会社コード）を渡した場合も同じで、変換までは成功し、ロード（書き込み）で失敗します。
接続設定は、レシピから使用されている状態でも削除できます。削除すると、そのレシピは実行時にエラーになります。
接続設定を削除する前に、使用しているレシピがないかを確認してください。（接続設定を削除する）
接続設定やインポート設定は、レシピとは別に管理されています。これらを後から変更・削除すると、レシピ側を何も変更していなくても、次の実行から失敗することがあります。
失敗が急に始まった場合は、レシピが参照している接続設定やインポート設定に変更がなかったかを確認してください。（接続設定を編集する）