Microsoft Fabricでの Spark ジョブのトラブルシューティング ガイド

このガイドを使用して、Microsoft Fabricで Spark ジョブを実行するときの一般的な問題を特定して解決します。 各セクションには、エラーの例、根本原因、および効率的な回復に役立つ実行可能な手順が含まれています。

Note

このガイドでは、Spark の実行エラー、ランタイム エラー、ジョブ固有の問題について説明します。 容量と調整のエラー、アクセス許可と承認エラー、セッション タイムアウト エラー、またはライブラリのインストール エラーについては、「アクセス許可と容量エラーのトラブルシューティング」、Fabricノートブックのトラブルシューティング ガイド、および Apache Spark ライブラリの管理に関するページを参照してください。

Spark ジョブに関する一般的な問題の概要

これらは、Fabricの Spark ジョブの問題の最も一般的なカテゴリと、関連するエラー コードです。 この表を使用して、エラーに関連するセクションにすばやく移動します。 関連する手順を試しても問題が解決しない場合は、「 サポートに問い合わせるタイミング」を参照してください。

セクション 説明
メモリと Executor のエラー メモリ不足エラー (終了コード 137)、Executor のクラッシュ、コンテナーの強制終了エラー、およびノードの不良エラー。 Spark_Ambiguous_Executor_MaxExecutorFailures、Spark_System_Executor_ExitCode137BadNode、メモリ チューニング戦略が含まれます。
INCONSISTENT_BEHAVIOR_CROSS_VERSION 動作、パフォーマンス、または結果の変更など、Spark ランタイム バージョンのアップグレード後の問題。
Spark での AnalysisException SQL クエリ分析エラー、スキーマの不一致、列解決エラー。 ANALYSIS_EXCEPTION、Spark_Ambiguous_SQL_AnalysisException、Delta Lake 分析の例外が含まれます。
セッションの起動とエラーの送信 Spark セッション初期化タイムアウト、SparkSubmit エラー、構成パーソナル化エラー。 SparkContextInitializationTimedOut、SparkSubmitProcessTimedOut、PersonalizationFailed、YARN アプリケーションの起動に関する問題が含まれます。
ストレージと接続のエラー ABFS ストレージ アクセスエラー、JDBC 接続エラー、およびSQL Server例外。 Spark_Ambiguous_ABFS_StorageAccountDoesNotExist、Spark_System_ABFS_OperationFailed、Spark_Ambiguous_JDBC_ConnectionFailed、Spark_Ambiguous_JDBC_SQLServerExceptionが含まれます。
ファイルとパスのエラー ファイルが見つからないエラー、パスが存在しないエラー、不正なパス参照。 Spark_User_FileInput_FileNotFoundとSpark_User_SQL_PathDoesNotExistが含まれます。
認証とトークンのエラー トークン プロバイダーのエラー、未承認のアクセス (403)、認証エラー。 UNABLE_TO_GENERATE_SESSION_TOKEN_WITH_TOKEN_PROVIDER、Spark_Ambiguous_CustomTokenProvider_Unauthorized、Spark_User_ABFS_Unauthorized、TOKEN_PROVIDER_USER_ERRORが含まれます。
Delta Lake とストリーミング エラー Delta Lake データ変換の例外、ストリーミング クエリの失敗、チェックポイントの問題。 Spark_Ambiguous_DeltaLake_DataTransformationExceptionとSpark_Ambiguous_DeltaLake_StreamingQueryExceptionが含まれます。
アプリケーション コード エラー NullPointerException、IllegalStateException、Pythonエラーなどのユーザー コード例外。 Spark_Ambiguous_UserApp_NullPointer、Spark_Ambiguous_UserApp_JobAborted、Spark_User_NonJvmUserApp_TypeError、Spark_User_UserApp_KeyError、およびSpark_User_UserApp_AttributeErrorが含まれます。
ライブラリと環境のエラー ライブラリのインストール エラー、pip エラー、conda 環境の問題、およびパッケージの依存関係の競合。 Spark_User_Conda_PipFailed が含まれます。
プラットフォームとエンジンのエラー ネイティブ実行エンジンのエラー、メタストア/Hive 例外、プラットフォーム レベルのエラー。 Spark_System_NativeExecutionEngine_InvalidStateとSpark_System_MetaStore_HiveExceptionが含まれます。
NotebookUtils EmptyString ノートブック パラメーターまたはシークレットにアクセスするときに空の文字列を返す NotebookUtils に関連するエラー。 Spark_Ambiguous_MsSparkUtils_EmptyString が含まれます。

Spark UI にアクセスする

Spark UI は、詳細な実行メトリックとログを表示するための Apache Spark の組み込みの監視インターフェイスです。 Fabric ポータル内からアクセスすると、Spark ジョブに関する低レベルの診断情報を提供する別のブラウザー ベースのインターフェイスとして開きます。 このガイド全体を通して、トラブルシューティング手順では Spark UI の特定のタブを参照して、 Executors タブでの終了コードの確認、 [ステージ ] タブでのデータスキューの検出、 ストレージ タブでのメモリ使用量の確認などの根本原因を特定するのに役立ちます。失敗した Spark ジョブまたは実行時間の遅い Spark ジョブを調査する必要がある場合は常に、Spark UI にアクセスします。

アプリケーションの Spark UI にアクセスするには:

  1. Fabric ワークスペースの左側のナビゲーションから省略記号 (...) を選択し、[モニター] を選択してモニター ハブを開きます。

  2. モニター ハブで、[ フィルター ] ボタンを選択します。

  3. アイテムの種類でフィルター処理し、表示するアイテムの種類 (Notebook など) を選択します。

  4. アクティビティのテーブルからアクティビティ 名 を選択して、アクティビティの詳細ページを開きます。

  5. [ジョブ] タブを選択します。

  6. ジョブの 説明 を選択して、Spark UI を新しいタブで開きます。

Spark UI のキー タブ:

  • ジョブ - アクティブな Spark ジョブと完了した Spark ジョブを表示します。

  • ステージ - タスク レベルの期間とデータ サイズを示します (スキュー検出に役立ちます)。

  • Storage — キャッシュされたデータフレームとメモリ使用量を示します。

  • 環境 — すべてのアクティブな Spark 構成を表示します。

  • Executor — Executor の状態、メモリ、終了コードを表示します。

ログにアクセスする方法

Spark UI はジョブの実行パターンとリソースの使用状況に関する視覚的な分析情報を提供しますが、特定のエラー メッセージのトラブルシューティング、スタック トレースの調査、またはアプリケーション出力 (stdout/stderr) の確認時に、テキスト ログ ファイルをダウンロードする必要があります。 エラーの正確な表現を確認する必要がある場合、詳細なドライバーまたは Executor ログを使用してエラーをトレースする場合、または実行中にコードで出力された内容を確認する必要がある場合は、ログを使用します。

Spark ログ (ドライバー ログ、Executor ログ、stdout、stderr) を表示またはダウンロードするには:

  • 監視ハブ ([ログ] タブ): 監視ハブで、 Apache Spark アプリケーションを選択し、アプリケーションを選択してから、[ ログ ] タブを選択します。左側のパネルから 、ドライバー、 Livy、または 事前起動 ログを選択します。 キーワード検索を使用するか、Notebook または Lakehouse で高コンカレンシー セッションをフィルターし、ログのダウンロード を選択してローカルに保存します。 ジョブがキューに登録されている場合、またはクラスターの作成に失敗した場合は、ログを使用できない可能性があります。 その場合は、容量メトリック アプリで容量使用率を確認します。

  • 拡張 Spark History Server: 完成したアプリケーションの場合は、アプリケーションの詳細ページから履歴サーバーを開きます。 [ 診断 ] タブは、データ スキュー、タイム スキュー、Executor 使用状況分析に使用します。 [Executors] タブには、Executor ごとのログのダウンロードが表示されます。 実行時間の長いジョブ (1 時間以上、または Executor ログが 16 MB を超える) の場合、ログは自動的に時間単位のセグメントに分割され、ナビゲーションが容易になります。

  • Spark 監視 REST API:プログラムによるログ取得または自動ログ取得のために、Fabricはドライバー ログ、Executor ログ、およびアプリケーション メタデータ用の REST API を提供します。 詳細については、「 Spark 監視 API を使用した Spark アプリケーションの監視」を参照してください。

  • VS Code: VS Code でノートブックを使用する場合は、[ 最近の実行の表示] を選択し、実行を選択してから、stdout、stderr、Spark ドライバー ログなどのログをダウンロードします。

ログへのアクセス、実行時間の長いジョブの Executor ローリング ログの表示、ログのトラブルシューティングの詳細については、「 Apache Spark アプリケーションの詳細監視 」および「 拡張 Apache Spark 履歴サーバーを使用して Apache Spark アプリケーションをデバッグおよび診断する」を参照してください。

メモリと Executor のエラー

Spark MaxExecutorFailures

このエラーは何を意味しますか? 「承認済みの標準 DCasV5/ECasv5 Family Cores クォータを超過することになるため、操作を完了できませんでした」

エラー コード Spark_Ambiguous_Executor_MaxExecutorFailuresは、クラッシュした Executor プロセスが多すぎるため、Spark アプリケーションが終了したことを意味します。 Spark は Executor 間で作業を分散します。1 つがクラッシュすると、Spark によって再試行されます。 ただし、エグゼキューターがしきい値を超えて失敗し続ける場合、Spark はジョブ全体を中止します。

Important

このエラーは常に症状であり、根本原因ではありません。 本当の質問は、エグゼキューターが失敗する理由です。

表示される一般的なメッセージ:

ExecutorLostFailure (executor N exited caused by one of the running tasks)  
Reason: Container killed on request. Exit code is 137

Max number of executor failures (N) reached

手順 1: 終了コードを見つける

Spark UI で、[ Executors ] タブを選択して、失敗した Executor の終了コードを確認します。

終了コード Meaning 最も可能性の高い原因
137 OS によって強制終了された (SIGKILL) メモリ不足: コンテナーがメモリ制限を超えました
143 終了 (SIGTERM) タイムアウト、プリエンプション、またはノードの使用停止
134 中止されました (SIGABRT) JVM クラッシュまたはネイティブ メモリの破損
1 一般的なエラー ユーザー コードの例外、構成の誤り、または依存関係の欠落
-100 コンテナがプリエンプトされた/消失した コンテナーが割り込まれたか、ノードが失われました

手順 2: シナリオに合わせる

シナリオ A — 終了コード 137 (メモリ不足)

表示内容: ドライバーログに「要求によりコンテナーが強制終了されました。」と表示されます。 終了コードは 137" です。

Container killed by YARN for exceeding memory limits. 7.1 GB of 7 GB physical memory used.

発生する理由: Executor によって処理されるデータが、その合計メモリ (ヒープ + オーバーヘッド) を超えています。 一般的なトリガー: データ スキュー、大きなパーティション、過剰なキャッシュ、大きなテーブルを使用したブロードキャスト結合、PySpark UDF、シャッフル スピル操作用のディスク領域が不足しています。

対処方法:

Important

%%configureではなく、spark.conf.set()をリソース構成に使用します。spark.executor.*、spark.driver.*、spark.network.*、およびspark.yarn.*の設定はセッションまたは Executor の起動時に読み取られ、spark.conf.set()とのセッションの途中で変更することはできません。 これらは、ノートブックの最初のセル (他のコードの前) として %%configure セルに配置するか、Fabric環境に設定します。 spark.sql.*を使用して実行時に変更できるのは、spark.conf.set()設定 (AQE、シャッフル パーティション、ブロードキャストしきい値、リベース モード) のみです。 %%configure セルは最初のセルである必要があり、実行時にセッションを再起動します。

  • Executor のメモリとオーバーヘッドを増やす:

    spark.conf.set("spark.executor.memory", "<VALUE>")  # Small=4g, Medium=8g, Large=16g, XLarge=28g
    spark.conf.set("spark.executor.memoryOverhead", "<VALUE>") # Small=2g, Medium=4g, Large=6g, XLarge=8g
    
  • パーティションを再分割して、より小さく均一なパーティションを作成します。

    Nの値を選択するには、開始点として推定データ サイズを 200 MB で除算します (たとえば、40 GB のデータが repartition(200) にマップされます)。 パーティションあたり 128 ~ 256 MB を目指し、Spark UI の [ステージ ] タブで実際のタスク入力サイズを確認します。

    df = df.repartition(N)  # Increase N to reduce per-partition size
    
  • アダプティブ クエリの実行 (AQE) を有効にする:

    アダプティブ クエリ実行は、すべてのFabric ランタイムで既定で有効になっています。 便利なレバーは、歪んだ結合を処理するための spark.sql.adaptive.skewJoin.enabled などのサブ設定です。 偏った結合がある場合、AQE を有効にすると、Spark は大きなパーティションを分割することで、実行時にスキューを自動的に検出して処理できます。

    spark.conf.set("spark.sql.adaptive.enabled", "true")  
    spark.conf.set("spark.sql.adaptive.skewJoin.enabled", "true")
    
  • キャッシュを減らす: キャッシュデータフレームのみが複数回再利用されます。完了したら、 df.unpersist() を呼び出します。

  • 大規模なテーブルのブロードキャストを無効にする:

    spark.conf.set("spark.sql.autoBroadcastJoinThreshold", "-1")
    
シナリオ B — 終了コード 143 (SIGTERM: タイムアウト、スケールダウン、またはプリエンプション)

表示内容: ドライバーログに「Executor heartbeat timed out after 120000 ms」または「ExecutorLostFailure」と表示されます。

発生する理由: 終了コード143はSIGTERMであり、正常終了を示すシグナルです。 動的割り当て (既定Fabric) では、FabricがSIGTERMを送信してアイドル状態の Executor をスケールダウンするため、このコードは通常どおりです。 すべての Executor が 143 で終了し、ジョブが完了した場合、アクションは必要ありません。

アクティブな作業中に Executor が 143 で終了した場合、原因は通常次のいずれかになります。

  • 実行プログラムがガベージ コレクション (GC) でスタックしているとき、または大きなタスクを処理している場合のハートビート タイムアウト。
  • ノードのプリエンプションまたは使用停止。
  • プラットフォームによって開始されたスケールダウン。

ジョブが失敗した場合、またはエグゼキューターがステージの途中で終了コード143で終了した場合にのみ、さらに調査してください。

対処方法:

  • ハートビートとネットワークのタイムアウトを増やす:

    spark.conf.set("spark.executor.heartbeatInterval", "60s")  
    spark.conf.set("spark.network.timeout", "800s")
    
  • GC の負荷が原因の場合、実際の問題はメモリです。 Executor のメモリとオーバーヘッドを増やし、データを再パーティション分割して小さなパーティションを作成し、AQE を有効にし、キャッシュを減らします (詳細な手順については 、シナリオ A を参照してください)。

  • タスクが大きなパーティションを処理しているかどうかを確認します (パーティションを小さいサイズに再分割します)。

シナリオ C — データ スキュー (少数の Executor が繰り返し失敗する)

表示される内容: ほとんどのタスクはすぐに完了しますが、かなり時間がかかり、失敗するタスクもあります。 同じエグゼキューターが繰り返し失敗します。

確認方法: Spark UI で、[ ステージ ] タブを選択し、失敗したステージを選択して、[ 期間] 列と [ 入力サイズ] 列を確認します。 一部のタスクの入力が他のタスクより 10~100 倍多い場合、データスキューが発生しています。

対処方法:

  • AQE スキュー結合処理を有効にします。 アダプティブ クエリ実行は、すべてのFabric ランタイムで既定で有効になっています。 便利なレバーは、歪んだ結合を処理するための spark.sql.adaptive.skewJoin.enabled などのサブ設定です。 AQE を有効にすると、Spark は、大きなパーティションを分割することで、実行時にスキューを自動的に検出して処理できます。

    spark.conf.set("spark.sql.adaptive.enabled", "true")  
    spark.conf.set("spark.sql.adaptive.skewJoin.enabled", "true")
    
  • ソルトを使用して大きなパーティションを分割する:

    from pyspark.sql.functions import rand  
    df = df.withColumn("salt", (rand() * N).cast("int"))  
    # Join/group on (key, salt), then aggregate without salt
    
  • 著しく偏ったキーは、フィルタリングするか、別途処理します。

シナリオ D — ストレージ/接続エラー

表示される内容: ドライバー ログには、 java.io.IOException: ABFS operation failed、接続拒否、 HTTP 403/401 エラー、または調整 (HTTP 429/503) が表示されます。

対処方法:

  • ストレージ アカウントにアクセスでき、アクセス許可が正しいことを確認します。

  • 認証トークンがまだ有効かどうかを確認します。 実行時間の長いジョブでは、トークンの有効期限が表示される場合があります。

  • スロットリングされた場合(429/503)は、並列度を下げるか、時間をずらして負荷を分散する。

  • ネットワーク セキュリティ グループ/ファイアウォール規則を確認します。

シナリオ E — ユーザー コードの例外 (終了コード 1)

表示される内容: Executor は終了コード 1で失敗します。 ドライバー ログには、アプリケーション コードからのスタック トレースが表示されます。

対処方法:

  • 完全なスタック トレースを読み取ります。コードの正確な行を指します。

  • UDF が null 値を正しく処理していることを確認します。

  • すべての Executor で必要なすべてのライブラリ/JAR が使用可能であることを確認します。

  • 最初に小さなデータセットでテストし、問題を特定します。

シナリオ F — PySpark/Pandas UDF がクラッシュする

表示される内容: エグゼキューターは Python UDF の実行中に失敗します。 終了コード 137 または "worker exiting" に関するメッセージ。

発生する理由:PySpark は、JVM と共に個別のPython プロセスを実行します。 どちらも同じノード メモリを共有します。

対処方法:

  • 可能な限り、Python UDF を組み込みの Spark SQL 関数に置き換えます。

  • Pandas UDF のバッチ サイズを小さくする:

spark.conf.set("spark.sql.execution.arrow.maxRecordsPerBatch", "5000")
  • メモリオーバーヘッドを増やす:
spark.conf.set("spark.executor.memoryOverhead", "<VALUE>")
シナリオ G — シャッフル中のディスク領域の枯渇

表示される内容: Executor は、シャッフル操作または並べ替え操作中に "デバイスに空き領域がありません" または "IOException" で失敗します。

発生する理由: Spark がメモリ内のデータを収めることができない場合は、ローカル ディスクにスピルします。 ローカル ディスクがいっぱいになると、Executor がクラッシュします。

対処方法:

  • シャッフルされたデータの量を減らす: 早期にフィルター処理し、必要な列のみを選択します。

  • シャッフル パーティションの数を増やして、パーティションごとのサイズを小さくします。

spark.conf.set("spark.sql.shuffle.partitions", "400")  # Default is 200
  • より多くのローカル ディスク領域を持つノードにスケールアップします。

  • データ スキューを確認します。歪んだパーティションは、1 つの Executor のディスクに不均衡にスピルします。

構成クイック リファレンス

メモリとリソース
Configuration Purpose
spark.executor.memory エグゼキュータごとのJVMヒープメモリ
spark.executor.memoryOverhead Python、ネイティブライブラリ向けのオフヒープメモリ
spark.driver.memory ドライバー用のJVMヒープメモリ
spark.driver.memoryOverhead ドライバーのオフヒープメモリ
エラー許容度
Configuration Purpose
spark.executor.maxNumFailures アプリが強制終了される前の Executor の最大合計エラー数
spark.executor.failuresValidityInterval エラーをカウントするための時間枠 (既定値: 無制限)
spark.task.maxFailures 個々のタスクあたりの最大再試行回数 (既定値: 4)

Important

障害許容度を高くしても、根本原因は解決されません。 それによって、ジョブがより多くの一時的な障害に耐えられるようになるだけです。

実行時間の長いジョブの場合は、 spark.executor.failuresValidityInterval を時間枠 ("1h" など) に設定します。 これにより、Spark カウントはその期間内のエラーのみになるため、何時間も実行されているジョブは、数時間離れて発生した一時的な障害によって強制終了されることはありません。

ネットワークとタイムアウト
Configuration Purpose
spark.network.timeout 一般的なネットワーク タイムアウト (既定値: 120 秒)
spark.executor.heartbeatInterval ハートビートの頻度 (既定値: 10 秒)
spark.sql.adaptive.enabled アダプティブ クエリ実行を有効にします (実行時にシャッフル パーティションと結合戦略を動的に最適化します)。 アダプティブ クエリ実行は、すべてのFabric ランタイムで既定で有効になっています。 便利なレバーは、歪んだ結合を処理するための spark.sql.adaptive.skewJoin.enabled などのサブ設定です。 AQE を有効にすると、Spark は、大きなパーティションを分割することで、実行時にスキューを自動的に検出して処理できます。
spark.sql.shuffle.partitions シャッフル後のパーティション (既定値: 200)
例: %%configure 経由での適用
%%configure  
{  
"conf": {  
"spark.executor.memory": "<VALUE>",  
"spark.executor.memoryOverhead": "<VALUE>",  
"spark.executor.maxNumFailures": "<VALUE>",  
"spark.network.timeout": "800s",  
"spark.executor.heartbeatInterval": "60s",  
"spark.sql.adaptive.enabled": "true", 
"spark.sql.adaptive.skewJoin.enabled": "true"  
}  
}

Fabricでは、一部の構成は、ノード サイズに基づいてプラットフォームによって管理されます。 Spark 構成プロパティの完全な一覧については、「 Apache Spark の構成」を参照してください。

スケーリング オプション

Option 使用するタイミング
スケールアップ (大規模なノード) 各 Executor は、より多くのメモリ/CPU を取得します (OOM リスクが軽減されます)
スケールアウト (その他のノード) データがより多くの Executor に分散される (Executor ごとの負荷が軽減されます)
最初に最適化する 傾斜したワークロードにリソースを追加しても役に立ちません。特大パーティションは引き続き 1 つの Executor に置かれる

トラブルシューティング早見表

観察 考えられる原因 最初のアクション
すべての Executor が終了コード 137 で失敗する OOM Executor のメモリ/オーバーヘッドを増やす。データ スキューのチェック
すべての Executor が終了コード 143 で失敗する ハートビートタイムアウト ネットワーク タイムアウトとハートビート間隔を増やす
少数の Executor のみが繰り返し失敗する データの偏り AQEのスキュー結合を有効にする;データを再パーティション化する
同じノードでエラーが発生する 障害のあるノード ジョブを再試行します。同じノードが再び失敗した場合は、サポートにお問い合わせください
エラーは I/O 操作と関連付けられる ストレージ接続 ストレージ アクセス、ファイアウォール、トークンの有効性を確認する
失敗時にユーザー コードのスタック トレースが表示される アプリケーションのバグ コードを修正する: null 処理、lib が見つからない
PYTHON UDF の実行中のエラー Python プロセス OOM memoryOverhead を増やします。UDF を SQL 関数に置き換える
"デバイスに空き領域が残っていない" というエラー ディスク領域の枯渇 シャッフル パーティションを増やす。早期にフィルター処理する。ノード サイズのスケールアップ

終了コード 137/ コンテナーが要求時に強制終了されました

このセクションでは、終了コード 137 で示Microsoft Fabric Spark ジョブのメモリ不足 (OOM) エラーについて説明します。 YARN は、割り当てられたメモリ制限を超えるとコンテナーを強制終了し、終了コード 137 (SIGKILL) を生成します。 これは Spark で最も一般的な OOM シグナルです。

このエラーは何を意味しますか? 「承認済みの標準 DCasV5/ECasv5 Family Cores クォータを超過することになるため、操作を完了できませんでした」

終了コード 137 は、YARN のコンテナー メモリ モニターが、割り当てられたメモリ制限を超えたために Executor (またはドライバー) コンテナーを終了したことを意味します。 Spark アプリケーションには、そのコンテナーが割り当てられたよりも多くのメモリが必要です。

Note

Linux の OOM キラーでも終了コード 137 が返されることがあります(OS 自体がメモリ不足に陥った場合)が、Fabric では「メモリ制限を超過したため、YARN によってコンテナーが強制終了された」というメッセージは、OS レベルの OOM キラーではなく、YARN がコンテナーのメモリ制限を適用したことを示しています。

コンテナー メモリの計算方法

各 Executor は、合計メモリが次の YARN コンテナー内で実行されます。

Container size = spark.executor.memory + spark.executor.memoryOverhead

JVM ヒープ、オフヒープ バッファー、Python プロセス、ネイティブ ライブラリの組み合わせメモリ使用量がこのコンテナー サイズを超えると、YARN によってコンテナーが強制終了されます (終了コード137)。

Fabric ノードには、32 GB、64 GB、128 GB、512 GB などのサイズがあります。 Spark UI の [ ストレージ ] タブ で、メモリ内のサイズ がノードの合計 RAM に近づくと、アプリケーションが OOM のリスクにさらされます。

Important

Fabricでは、spark.executor.memoryOverheadは、max(384 MB, 0.1 × executor memory)のオープンソース Spark の既定値とは異なり、ノード サイズに関係なく固定の 384 MB に設定されます。 PySpark UDF、大きなシャッフル、ネイティブ ライブラリなどのメモリ集中型ワークロードでは、多くの場合、384 MB では不十分です。 spark.executor.memoryOverhead明示的に高い値に設定します。

メモリ チューニングの詳細なガイダンスについては、「 Spark チューニング ガイド: メモリ管理」を参照してください。

確認すべきエラー メッセージ

java.lang.OutOfMemoryError: Java heap space

java.lang.OutOfMemoryError: GC overhead limit exceeded

Container killed on request. Exit code is 137  
Container exited with a non-zero exit code 137  
Killed by external signal

os::commit_memory failed; error='Cannot allocate memory' (errno=12)  
Native memory allocation (mmap) failed to map <N> bytes

確認する場所

  • Spark UI の [Executors] タブ: 失敗した Executor とその終了コードを確認する

  • Spark UI の [ストレージ] タブ: ノード サイズに対する "Size in Memory" (メモリ内のサイズ) を確認する

  • Spark UI の [ステージ] タブ: 傾斜したタスクを確認する (1 つのタスクが他のタスクよりもはるかに多くのデータを処理する)

  • ドライバーログ (stderr):OutOfMemoryError、終了コード137、またはCannot allocate memoryを検索してください

一般的な原因と修正

1. collect()、toPandas()、または display() によるドライバーのOOM

症状: ドライバー プロセスのメモリ不足。 多くの場合、クラッシュ時に Spark タスクは実行されません。

原因: これらの操作により、データセット全体が Executor からドライバー メモリにプルされます。

対処方法:

  • .limit(N)またはcollect()の前にtoPandas()を追加して、返される行を制限します。

  • .writeを使用して、ドライバーに収集するのではなく、結果をストレージに保存します。

  • display(df.limit(1000))の代わりに display(df) を使用します。

  • toPandas()を使用する必要がある場合は、最初にデータをフィルター処理または集計します。

2. データスキューによる Executor OOM

症状: ほとんどのタスクはすぐに完了しますが、終了コードの 137には時間がかかり、失敗します。

原因: データ分散が不均等な場合、いくつかの Executor が他の実行プログラムよりも多くのデータを処理します。

対処方法:

  • 傾斜したキーを特定する: [Spark UI ステージ] タブでタスク期間の差異を調べます。

  • ソルトを使用して、大きなパーティションを分割します。

  • AQE スキュー結合処理を有効にします。 アダプティブ クエリ実行はすべてのFabricランタイムで既定で有効になるため、スキューのキー レバーはspark.sql.adaptive.skewJoin.enabled。これにより、Spark は実行時に大きなパーティションを検出して分割できます。

spark.conf.set("spark.sql.adaptive.enabled", "true")  
spark.conf.set("spark.sql.adaptive.skewJoin.enabled", "true")
3. データをキャッシュしすぎることによる Executor の OOM

症状: キャッシュされた DataFrame が蓄積されると、メモリ使用量は時間の経過と同時に上昇します。

原因: 複数の大規模な DataFrame で .cache() または .persist() を解放せずに呼び出します。

対処方法:

  • 複数回再利用される DataFrame のみをキャッシュします。

  • 完了したら、永続化を解除します: df.unpersist()。

  • MEMORY_AND_DISKの代わりにストレージ レベルMEMORY_ONLY使用します。

from pyspark import StorageLevel  
df.persist(StorageLevel.MEMORY_AND_DISK)
4. パーティション数が少なすぎることによる Executor OOM

現象: タスクは、パーティションごとに大量のデータを処理します。

原因: DataFrame には、データ サイズに対するパーティションが少なすぎます。

対処方法:

  • 並列処理を向上させるためにパーティションを再分割する:
df = df.repartition(N)  # Choose N based on your data size
  • それぞれ約 128 ~ 256 MB のパーティションを目指します。

  • 書き込みの場合は、 coalesce() のみを使用してパーティションを減らします (大きなデータの場合は 1 にしないでください)。

5. ブロードキャスト結合 OOM

症状: 結合操作中に、ドライバーまたはエグゼキューターで OOM が発生する。

原因: Spark は、大きすぎるテーブルをブロードキャストします。

対処方法:

  • 大規模なテーブルの自動ブロードキャストを無効にする:
spark.conf.set("spark.sql.autoBroadcastJoinThreshold", "-1")
  • または、しきい値を減らします。
spark.conf.set("spark.sql.autoBroadcastJoinThreshold", "10MB")
6. PySpark UDF /Pandas UDF のメモリ不足

現象: UDF の実行中に Executor メモリが急増する。 コード 137を終了します。

原因:PySpark UDF は、JVM Executor と共に別のPython プロセスで実行されます。 どちらも同じノード メモリで競合します。

対処方法:

  • 可能な場合Python UDF を組み込みの Spark SQL 関数に置き換えます。

  • Pandas UDF の場合は、バッチ サイズを小さくします。

spark.conf.set("spark.sql.execution.arrow.maxRecordsPerBatch", "5000")
  • メモリオーバーヘッドを増やす:
spark.conf.set("spark.executor.memoryOverhead", "<VALUE>")
7. ネイティブ実行エンジンのオフヒープ メモリプレッシャー

症状: Executor は、ワークロードが以前に問題なく実行されていた場合でも、終了コード 137 で失敗します。または、メモリを集中的に消費していないクエリで OOM が発生します。

原因:Fabric ネイティブ実行エンジンでは、動的サイズ設定を使用して、既定でオフヒープ メモリが有効になります。 場合によっては、ネイティブ エンジンがクエリをアクティブに処理していない場合でも、これはヒープ以外のメモリの大部分を予約し、JVM ヒープ メモリに負荷をかけ、OOM を引き起こします。

対処方法:

  • ネイティブ実行エンジンを無効にして、それが原因であることを確認してみてください。
spark.conf.set("spark.fabric.nativeExecution.enabled", "false")
  • OOM が消えても、ネイティブ エンジンのメモリ割り当てがトリガーでした。 サポートに問い合わせながら、回避策として無効にして実行します。

  • 無効にした後も OOM が解決しない場合、問題は本物のメモリ不足です。 このセクションの他の修正プログラムを適用します。

8. 大規模なクエリ プラン (AQE) からのドライバー OOM

症状: データの処理中ではなく、クエリの計画中に OutOfMemoryError でドライバーがクラッシュします。 エラー メッセージには、「必要な配列の長さ ... は大きすぎます」が含まれる場合があります。

原因:アダプティブ クエリ実行 (AQE) は、すべてのFabric ランタイムで既定で有効になっています。 クエリが非常に複雑な場合 (多くの結合、共用体、またはキャッシュされたデータフレーム)、Spark はプランの変更ごとにクエリ プランのテキストを再生成します。 プラン文字列が非常に大きいと、メモリ制限を超える可能性があります。

対処方法:

  • プラン文字列の長さを制限します。
spark.conf.set("spark.sql.maxPlanStringLength", "10000")
  • 問題が解決しない場合は、この特定のジョブの AQE を無効にします。
spark.conf.set("spark.sql.adaptive.enabled", "false")
  • クエリを簡略化します。ストレージへの中間書き込みを使用して、より小さな手順に分割します。

一般的なチューニング オプション

オプション A: スケールアップ (ノード サイズを増やす)

Spark プールのノード サイズを大きくします (たとえば、小から中、大)。

オプション B: スケールアウト (ノードを追加)

Executor/ノードの数を増やして、より多くのノードにデータを分散します。

オプション C: Executor あたりの同時実行タスクを減らす

各 Executor は、複数のタスクを並列で実行します (コアごとに 1 つ)。 同時実行タスクの数を減らすと、各タスクのメモリが増え、メモリ負荷の高い操作で OOM を防ぐことができます。

spark.conf.set("spark.executor.cores", "2")  # Default varies by node size

同時実行タスクの数が少ないほど、スループットは低下しますが、タスクあたりのメモリが多くなります。 これは、個々のタスクがメモリを大量に消費する (大規模な集計、複雑な UDF) 場合に使用します。

オプション D: Spark 構成を調整する
Configuration Purpose
spark.driver.memory ドライバー ヒープ メモリを増やす
spark.executor.memory Executor のヒープメモリを増やす
spark.driver.memoryOverhead ドライバー用の追加のオフヒープメモリ (既定値: 384 MB)
spark.executor.memoryOverhead Executor の余分なオフヒープ メモリ (既定値: 384 MB)
spark.executor.cores Executor あたりのコア数 (コア数が少ない = タスクあたりのメモリの数が多い)
spark.sql.adaptive.enabled AQE 自動チューニングを有効にします (Fabric では既定で有効)
spark.sql.adaptive.skewJoin.enabled 歪んだ結合を自動処理する (AQE が既にオンになっているため、キー レバー)
spark.sql.autoBroadcastJoinThreshold テーブルがブロードキャストされるタイミングを制御する
spark.sql.shuffle.partitions シャッフル後のパーティション数 (既定値: 200)
spark.sql.maxPlanStringLength クエリ プランの文字列の長さを制限する (複雑なプランではドライバー OOM を防ぎます)
オプション E: コードを最適化する
回避するパターン より良い代替手段
df.collect() 大きなデータの場合 df.write.parquet(path)
df.toPandas() 大きなデータの場合 df.limit(N).toPandas() またはストレージに保存する
df.repartition(1) 大きなデータの場合 df.coalesce(N) 妥当な N を用いて
.cache() すべて >1 回再利用された DataFrame のみをキャッシュする
UDF のPython 組み込みの Spark SQL 関数
for row in df.collect(): ... Spark 変換 (マップやフィルターなど) を使用する

Spark_System_Executor_ExitCode137異常ノード

このエラーは何を意味しますか? 「承認済みの標準 DCasV5/ECasv5 Family Cores クォータを超過することになるため、操作を完了できませんでした」

このエラー コードは、エグゼキューターが終了コード 137 (メモリ不足) で強制終了されたことを意味し、Fabric プラットフォームは、障害のフラグが付けられたノードでエラーが発生したことを識別したことを意味します。 通常の終了コード 137 とは異なり、この分類は、Executor が実行されている特定のノードでプラットフォームがインフラストラクチャ レベルの問題を検出したことを示します。

確認すべきエラー メッセージ

ExecutorLostFailure Container from a bad node: container_XXXX_0001_01_000046  
on host: vm-XXXXXXXX. Exit status: 137.  
Diagnostics: Container killed on request. Exit code is 137  
Container exited with a non-zero exit code 137.  
Killed by external signal

これは通常の終了コード 137 とどのように異なりますか?

特徴 終了コード 137 (通常) ExitCode137BadNode
根本原因 アプリケーションがメモリ制限を超えました 障害のあるノードが原因で Executor がクラッシュする
誰が原因ですか? 通常、ユーザー コードまたは構成 一般的にはプラットフォーム インフラストラクチャ
再試行の動作 どのノードでも同じエラーが繰り返し発生する可能性があります 通常、再試行は正常なノードで成功します
必要なアクション メモリの調整、スキューの修正、コードの最適化 ジョブを再試行してください。問題が解消しない場合は、サポートにお問い合わせください。

何をすべきか

手順 1: ジョブを再試行してください。 プラットフォームでは、通常、障害のフラグが設定されているノードでの作業のスケジュールを回避します。 ほとんどの場合、次の実行は正常なノードで成功します。

手順 2: 複数の再試行で同じノードでエラーが繰り返し発生する場合は、Spark アプリケーション ID と Spark UI Executors タブのノード情報をサポートにお問い合わせください。

手順 3: 異なるノードでエラーが繰り返し発生する場合、根本原因はインフラストラクチャではなくアプリケーションである可能性があります。 ワークロードに本物の OOM の問題があるかどうかを確認するには、上記の「終了コード 137」セクションを参照してください。

通常、このエラーが 1 回発生するのは一時的なものであり、コードを変更する必要はありません。 プラットフォームは、障害のあるノードの検出と削除を自動的に管理します。

不良ノードからのコンテナー / 終了ステータス: 50

このエラーは何を意味しますか? 「承認済みの標準 DCasV5/ECasv5 Family Cores クォータを超過することになるため、操作を完了できませんでした」

このエラーは、プラットフォームが異常または使用停止として検出されたノードで実行されていたため、Spark Executor コンテナーが終了したことを示します。 終了ステータス 50 はFabric固有のシグナルであり、アプリケーション コードではなく、ノード レベルの問題によってコンテナーが事前に強制終了されたことを示します。

確認すべきエラー メッセージ

Container from a bad node. Exit status: 50

ExecutorLostFailure (executor N exited caused by one of the running tasks)  
Reason: Container from a bad node. Exit status: 50

発生する理由

Fabric プラットフォームは、ノードの正常性を継続的に監視します。 ノードが異常として検出された場合 (ハードウェアの問題、ディスク障害、ネットワークの問題、またはその他のインフラストラクチャの障害により)、プラットフォームはそのノード上のコンテナーを終了して、データの破損やサイレント エラーを防ぎます。

一般的なトリガーは次のとおりです:

  • 基になるコンピューティング ノード (ディスク、メモリ、CPU) に関するハードウェアの問題

  • メンテナンス操作中に使用停止中のノード

  • ノードとクラスター マネージャーの間のネットワーク接続の損失

  • プラットフォームの正常性チェックに失敗しているノード

何をすべきか

手順 1: ジョブを再試行します。 通常、このエラーは一時的なものです。 プラットフォームは、障害のあるノードから後続の作業をルーティングし、次の実行は成功するはずです。

手順 2: 影響を受けた Executor の数を確認します。 終了ステータス 50 で失敗した Executor が 1 つまたは 2 つのみで、残りが正常に完了した場合、Spark の組み込み再試行メカニズムによってジョブが既に自動的に復旧されている可能性があります。

手順 3: これらのコンテナー損失によって、MaxExecutorFailures しきい値を超えた Executor の合計エラーがプッシュされたためにジョブが失敗した場合は、より多くの再試行を許可するようにエラー許容度を上げてください。

# Start 10–20 for production; 30–50 for long jobs with spark.executor.failuresValidityInterval="1h"
spark.conf.set("spark.executor.maxNumFailures", "20")  

Important

根本原因はコードではなくインフラストラクチャであるため、ここでは障害許容度を高めることが適切です。 OOM エラーとは異なり、ノードが正しくないエラーに対して再試行を増やせるようにすることは有効な軽減策です。

手順 4: 複数の再試行でエラーが解決しない場合や、同じ実行で多数の Executor に影響する場合は、サポートにお問い合わせください。 Spark アプリケーション ID とエラーのタイムスタンプを指定します。

OOM と区別する方法 (終了コード 137)

信号 終了コード 137 (OOM) 終了ステータス 50 (ノードが正しくありません)
エラー メッセージ "要求時にコンテナーが強制終了されました。 終了コードは 137" 不良ノードからのコンテナ。 終了ステータス: 50"
根本原因 アプリケーションがメモリ制限を超えました ノード インフラストラクチャの障害
Pattern 多くの場合、複数のエグゼキューターに影響するか、再試行時に再発する 通常は 1 ~ 2 個の実行プログラムに影響します。再試行時に解決される
修正 メモリの調整、スキューの修正、コードの最適化 ジョブを再試行します。必要に応じて maxNumFailures を増やす

バージョン間で動作が一貫しない

このエラーは、Spark アプリケーションがランタイム バージョンの変更後に異なる結果を生成しているか、失敗しているか、動作が異なっているかを示します。 以前のバージョンで動作していたのと同じコードとデータによって、予期しない出力、エラー、またはパフォーマンスの低下が発生するようになりました。

Fabric ランタイム互換性マトリックス

コンポーネント ランタイム 1.1 ランタイム 1.2 ランタイム 1.3
Apache Spark 3.3 3.4 3.5
Java JDK 8 JDK 11 JDK 11
Scala 2.12 2.12 2.12
Python 3.10 3.10 4.4.1
R 4.2 4.2 4.3
Delta Lake 2.2 2.4 3.2

一般的なカテゴリ

カテゴリ 例示
Datetime/Timestamp の非互換性 異なる解析、プロレプティックグレゴリオ暦とユリウス暦
クエリ結果の違い さまざまな行数、値、または列の順序
既存のコードの新しいエラー ClassNotFoundException、非推奨の API の削除
パフォーマンスの低下 同じジョブにかかる時間が大幅に長くなる
Delta Lake の互換性 InvalidProtocolVersionException
ライブラリ/依存関係の不一致 パッケージバージョンの変更Python、Scala/Java アップグレード

カテゴリ A — Datetime とタイムスタンプの非互換性

発生する理由: Spark 3.0 以降は、ハイブリッドジュリアン/グレゴリオ暦からプロレプティック グレゴリオ暦に切り替えました。 以前の動作で記述された Parquet INT96 形式と datetime 形式が誤って解釈される可能性があります。 従来の datetime 設定が高コンカレンシー モードで正しく伝達されない場合があります。

手順 1: これが影響を受けるかどうかを特定します。 データ/ワークフローには以下が含まれますか。

  • 履歴の日付 (1900 より前か 1582 より前か)

  • 最近のアップグレードの前に作成された Parquet ファイル/テーブル

  • アップグレードされた環境またはコンカレンシーの高い環境でのみエラーが発生しますか?

  • INCONSISTENT_BEHAVIOR_CROSS_VERSIONまたはREAD_ANCIENT_DATETIMEを含むエラーログですか?

手順 2: datetime リベース モードの Spark 構成を設定します。

spark.conf.set("spark.sql.parquet.int96RebaseModeInRead", "CORRECTED")  
spark.conf.set("spark.sql.parquet.int96RebaseModeInWrite", "CORRECTED")  
spark.conf.set("spark.sql.parquet.datetimeRebaseModeInRead", "CORRECTED")  
spark.conf.set("spark.sql.parquet.datetimeRebaseModeInWrite", "CORRECTED")

Important

運用環境で使用する前に検証します。 CORRECTED モードを運用パイプラインに適用する前に、最初にサンプル データセットをテストします。 LEGACY の動作で最初に書き込まれたデータに CORRECTED を設定すると、過去の日付(1582 年以前)の日付値が気付かないうちにずれる可能性があります。 完全なパイプライン実行にコミットする前に、サンプルで SELECT MIN(date_col), MAX(date_col) FROM my_table を実行し、設定間で結果を比較します。 履歴の日付で結果が異なる場合は、既存のデータに LEGACY を使用し、新しいデータの CORRECTED への移行を計画します。

  • 環境間で新しい一貫性のある動作を行うには、"CORRECTED" を使用します (推奨)。

  • "LEGACY" は、アップグレード前のランタイムで書き込まれたデータが読み取りに失敗した場合にのみ使用します。

または、%%configureを介して:

%%configure  
{  
"conf": {  
"spark.sql.parquet.int96RebaseModeInRead": "CORRECTED",  
"spark.sql.parquet.int96RebaseModeInWrite": "CORRECTED",  
"spark.sql.parquet.datetimeRebaseModeInRead": "CORRECTED",  
"spark.sql.parquet.datetimeRebaseModeInWrite": "CORRECTED"  
}  
}

Important

高コンカレンシー モードでは、ノートブック/セッション レベルで設定を適用する必要があります。環境またはクラスター全体の設定が反映されない可能性があります。

手順 3: 検証:

  • 失敗したジョブ/ノートブックを再実行します。

  • 設定が有効になったかどうかを確認します。

print(spark.conf.get("spark.sql.parquet.datetimeRebaseModeInRead"))

カテゴリ B — Scala、Java、またはPythonバージョンの変更

Fabric ランタイム Spark Java Scala Python
ランタイム 1.1 3.3 JDK 8 2.12.15 3.10
ランタイム 1.2 3.4 JDK 11 2.12.17 3.10
ランタイム 1.3 3.5 JDK 11 2.12.18 3.11

対処方法:

  • 新しい Scala/Spark バージョンに対してカスタム JAR を再構築します。 Maven/SBT で Spark に指定されたスコープを使用します。

  • サードパーティ JAR を使用する ClassNotFoundException の場合は、JAR に正しい Scala サフィックス (例: _2.12) があることを確認します。

  • Python ModuleNotFoundError の場合は、不足しているパッケージを明示的にインストールします。

%pip install pandas==2.0.3

カテゴリ C — Delta Lake プロトコルの非互換性

発生する理由: Delta Lake では、プロトコル バージョンを使用してテーブル機能を追跡します。 プロトコルのアップグレードは元に戻すことができません。

Scenario 結果
ランタイム 1.2 での削除ベクトルの有効化、ランタイム 1.1 での読み取り 失敗: ランタイム 1.1 はプロトコルをサポートしていません
ランタイム 1.2 で TimestampNTZ を使用して作成されたテーブル リーダー バージョン 3 が必要: ランタイム 1.1 が読み取れない
ライター バージョン 6 で外部に書き込まれたテーブル Fabric Delta ランタイムでサポートされていない可能性があります

対処方法:

  • 前に進み、後方ではなく、プロトコルをサポートするランタイムを使用します。

  • 同じ Delta テーブルでランタイムを混在しないようにします。

  • 新しい機能を有効にする前にプロトコルを確認します。

DESCRIBE DETAIL my_table

カテゴリ D — Spark SQL の動作の変更

発生する理由: Spark バージョンでは、既定の動作 (ANSI モード、キャスト 規則、null 処理) が変更されます。

対処方法:

  • ANSI モードによりより厳密な動作が発生する場合:
spark.conf.set("spark.sql.ansi.enabled", "false")
  • 日付/時刻の解析の変更の場合:
spark.conf.set("spark.sql.legacy.timeParserPolicy", "LEGACY")
  • より厳密な INSERT 型チェックの場合:
spark.conf.set("spark.sql.storeAssignmentPolicy", "LEGACY")

レガシ設定の使用は、短期的な修正です。 新しい動作のためにコードを更新することを計画します。

Spark での AnalysisException

AnalysisExceptionは、Spark のクエリ分析フェーズ中に、データが処理される前にスローされます。 Spark は、SQL または DataFrame クエリを検証し、参照されているすべてのテーブル、列、関数、および型が存在し、互換性があることを確認します。 何かがチェックアウトされない場合、Spark はすぐにクエリを拒否します。 これはほとんどの場合、ユーザー側の問題です。入力ミス、テーブルの不足、スキーマの不一致、サポートされていない操作などです。 早期に失敗するため、コンピューティング リソースは無駄にされません。

一般的なエラー パターン:

org.apache.spark.sql.AnalysisException: Table or view not found: my_table

org.apache.spark.sql.AnalysisException: [UNRESOLVED_COLUMN.WITH_SUGGESTION]  
A column or function parameter with name 'NotARealColumn' cannot be resolved.  
Did you mean one of the following? [Revenue, GrossRevenue, Rating, Branch, City]

org.apache.spark.sql.AnalysisException: Data type mismatch: ...

手順 1: エラー メッセージを注意深く読む

AnalysisException メッセージには、ほとんどの場合、次のものが含まれています。

  • 失敗した内容: テーブル、列、関数、または操作

  • 失敗した理由: 見つからない、型の不一致、あいまいな参照

  • 使用可能な内容: 有効な列、テーブル、または型の一覧

列名の入力ミスの例:

AnalysisException: cannot resolve '`salery`' given input columns:  
[employee.name, employee.salary, employee.dept]

このエラーは、列名は実際には "salary" なのに、"salery" と入力したことを示しています。

手順 2: エラーをシナリオに一致させる

シナリオ A — テーブルまたはビューが見つかりません

Table or view not found: my_table
  • テーブル名にタイプミスがあります。スペルと大文字・小文字の区別を再確認してください。

  • 誤ったデータベース/スキーマです: 完全修飾名を使用してください。

spark.sql("SELECT * FROM my_catalog.my_schema.my_table")
  • 一時ビューの有効期限が切れた: セッションが再開された場合、ビューは失われます。 再作成します。
df.createOrReplaceTempView("my_table")
  • テーブルはまだ書き込まれていません。上流のノートブックまたはセルが完了していることを確認してください。

  • レイクハウスが接続されていません—Fabric で、レイクハウスがノートブックに接続されていることを確認してください。

シナリオ B — 列が見つかりません

[UNRESOLVED_COLUMN.WITH_SUGGESTION] A column or function parameter  
with name 'X' cannot be resolved.
  • 列名の入力ミス: エラーの候補と比較します。

  • 列の名前が変更されたか、アップストリームから削除されました。スキーマを確認します。

df.printSchema()
  • 列は別の DataFrame に存在します。結合後、正しいソースを参照します。
df1.join(df2, df1.id == df2.id).select(df1.id, df2.name)

シナリオ C — あいまいな列参照

[AMBIGUOUS_REFERENCE] Reference 'Quantity' is ambiguous,  
could be: [a.Quantity, b.Quantity]

実行する操作: テーブルの別名を使用して列を修飾します。

# SQL  
spark.sql("""
  SELECT a.id, b.name  
  FROM table_a a JOIN table_b b ON a.id = b.id  
""")

# DataFrame API  
df1.alias("a").join(df2.alias("b"), col("a.id") == col("b.id")) \
  .select("a.id", "b.name")

使用可能な SQL 関数の完全な一覧については、「 Spark SQL 組み込み関数」を参照してください。

シナリオ D — データ型の不一致

Data type mismatch: differing types in '(col_a = col_b)': int vs string

実行する操作: 共通の型に明示的にキャストします。

from pyspark.sql.functions import col  
df = df1.join(df2, df1["id"].cast("string") == df2["id_str"])

シナリオ E — 関数が見つかりません

Undefined function: 'my_function'
  • 入力ミス: Spark SQL 関数のリファレンスを確認します。

  • UDF が登録されていません:

spark.udf.register("my_function", my_function)
  • バージョン アップグレードで削除された関数: 移行ガイドを確認してください。

シナリオ F — 書き込み/INSERT でのスキーマの不一致

[_LEGACY_ERROR_TEMP_DELTA_0007] A schema mismatch detected  
when writing to the Delta table...

対処方法:

  • ターゲットが期待するものを確認します。
spark.sql("DESCRIBE my_table").show()
  • 記述内容を確認します。
df.printSchema()
  • 列と型を揃える:
df = df.select("col_a", "col_b", "col_c")  
df = df.withColumn("col_a", col("col_a").cast("int"))
  • Delta スキーマ進化について:
df.write.format("delta") \
  .option("mergeSchema", "true") \
  .mode("append") \
  .save("/path/to/table")

シナリオ G — Delta Lake AnalysisException

エラー 原因 修正
リーダー/ライター バージョン N が必要なテーブルに書き込めません デルタ プロトコルの非互換性 必要なプロトコルをサポートするランタイムを使用する
Delta テーブルへの書き込み時にスキーマの不一致が検出されました 新しいデータに余分な列または不足している列がある スキーマのマージを有効にするか、スキーマを修正する
互換性のない形式が検出されました デルタ以外の形式でデルタ パスに書き込む ターゲット パスが Delta テーブルであることを確認する
操作が許可されていません: パーティション列を変更できません パーティション分割を変更しようとしています 目的のパーティション分割を使用して新しいテーブルを作成する

Delta Lake スキーマの進化、テーブル機能、プロトコルバージョンの詳細については、 Delta Lake のドキュメントを参照してください。

シナリオ H — パス/ファイルが見つかりません

Path does not exist: abfss://container@account.dfs.core.windows.net/my/path
  • パスの入力ミス: コンテナー名、ストレージ アカウント、ファイル パスを再確認します。

  • ファイルが削除または移動されました。ファイルが lakehouse/Storage エクスプローラーに存在するかどうかを確認します。

  • 間違ったストレージ アカウントまたはワークスペース。

  • 権限の問題: 実際には "アクセスが拒否されました" であるにもかかわらず、エラーに "パスが見つかりません" と表示されることがあります。

Important

Fabric ノートブックでは、Spark を使用した nbresource フォルダーからの読み取りはサポートされていません。 ノートブックのリソース ファイルには、spark.read ではなく Python のファイル I/O (open()) を使用してください。 明示的なパスに書き込む場合は、.save()の代わりに.saveAsTable()を使用します。

シナリオ I — サポートされていない操作

Unsupported operation: ALTER TABLE ADD COLUMNS ... for non-Delta tables

実行する操作: 機能に差分形式が必要かどうかを確認します。 必要に応じて変換します。

from delta.tables import DeltaTable  
DeltaTable.convertToDelta(spark, "parquet.`/path/to/table`")

デバッグ手法

  • スキーマを印刷します。
df.printSchema()  
spark.sql("DESCRIBE EXTENDED my_table").show(truncate=False)
  • 使用可能なテーブルの一覧表示:
spark.sql("SHOW TABLES").show()
  • 使用可能な列の一覧表示:
spark.sql("DESCRIBE my_table").show()
  • クエリを段階的にテストする - ステップ バイ ステップでビルドします。
spark.sql("SELECT * FROM my_table LIMIT 5").show()  
spark.sql("SELECT col_a, col_b FROM my_table LIMIT 5").show()
  • Spark 構成を確認します。
for k, v in sorted(spark.sparkContext.getConf().getAll()):  
    print(f"{k} = {v}")

トラブルシューティング早見表

エラー メッセージに含まれるもの 考えられる原因 最初のアクション
テーブルまたはビューが見つかりません テーブルがないか、データベースが間違っている スペルを確認する; 完全修飾名を使用する
解決できない + 列名 列が存在しないか、列名のスペルが間違っています df.printSchema()または DESCRIBE テーブルを実行する
参照 ... は曖昧である 結合後に列名が重複する テーブルエイリアスを付けて指定: a.id
データ型が一致していません 互換性のない型の比較 列を共通型にキャストする
未定義関数 見つからない、または未登録の UDF スペル チェック;カスタムの場合は UDF を登録する
互換性のないデータを書き込めません 書き込み時のスキーマの不一致 ソースとターゲットのスキーマを比較する。cast/select
パスが存在しない 間違ったファイル パスまたは削除されたファイル ストレージ エクスプローラーでパスを確認する
安全にキャストできない INSERT での厳密な型チェック 書き込む前に列を明示的にキャストする
DeltaAnalysisException デルタ固有のスキーマ/プロトコルの問題 上の「Delta Lake」セクションを参照してください
サポートされていない操作です テーブル形式では使用できない機能 デルタ形式が必要かどうかを確認する

セッション開始時のエラーと送信時のエラー

SparkContextInitializationTimedOut

エラー: Spark_Ambiguous_ApplicationMaster_SparkContextInitializationTimedOut

発生する理由: タイムアウト期間内に Spark コンテキスト (ドライバー) を初期化できませんでした。 原因としては、クラスター リソースの不足、起動時のネットワークの問題、またはカスタム ライブラリのインストールに時間がかかりすぎることが挙げられます。

対処方法:

  • クラスターに十分なリソースがあるかどうかを確認します。他のジョブで容量が消費されている場合は、専用プールを待機または使用します。

  • カスタム ライブラリ/環境の構成 (大規模または多数のライブラリの初期化速度が遅い) を確認します。

  • ネットワーク接続の問題 (仮想ネットワーク構成、プライベート エンドポイント) を確認します。

  • 問題を特定するために、カスタム ライブラリの依存関係を削除または削減します。

SparkSubmit エラー

エラー Meaning
Spark Submit プロセスがタイムアウトしました spark-submit が長すぎてアプリケーションを起動できませんでした
SparkSubmitProcessFailedExitCode1 spark-submit がエラーで終了しました (正しくない構成、JAR がありません)
SparkSubmit プロセスが終了コード 143 で失敗しました spark-submit が強制終了されました (リソースの制限またはプラットフォームのタイムアウト)
PersonalizationFailed カスタム環境/ライブラリのセットアップに失敗しました
ConfigPersonalizationFailed カスタム Spark 構成の適用に失敗しました

対処方法:

  • タイムアウト: 大規模なカスタム ライブラリによって環境のセットアップが遅くなっているかどうかを確認します。 ライブラリの数/サイズを減らします。

  • 終了コード 1: ドライバー ログで実際のエラー (通常は構成ミスまたは依存関係がない) を確認します。

  • 終了コード 143: プロセスが強制終了されました。リソース不足の可能性があります。 再試行;永続的な場合は、サポートにお問い合わせください。

  • 個人用設定に失敗しました: カスタム環境の定義を確認します。 カスタム パッケージを 1 つずつ削除してみてください。

  • 構成のパーソナル化に失敗しました: Spark 構成キーが有効であることを確認します。 一部の構成は、マネージド環境では読み取り専用です。

YARN アプリケーション — KilledByTrustedServiceUser

エラー: Spark_System_YARNApplication_KilledByTrustedServiceUser

意味: Spark セッションが起動中に失敗しました。コードの実行が開始される前に YARN アプリケーションが強制終了されました。 終了コードは通常 13 です。

シナリオ 1 — Spark 構成が無効です

発生する理由: 正しくない Spark 構成またはサポートされていない Spark 構成が渡されたため、起動時にセッションがクラッシュしました。

一般的な例:

  • プレーン整数の代わりに単位サフィックス (例: "512m") が設定された spark.rpc.message.maxSize

  • spark.rpc.message.maxSize が最大値である 2047 MB を超える値に設定されている

  • spark.network.timeout が spark.executor.heartbeatInterval より小さい値に設定されている

対処方法:

  • ノートブックの %%configure セルまたは環境設定で、すべてのカスタム Spark 構成を確認します。

  • 最近追加した構成キーを削除し、再実行します。

  • 数値構成で予期される単位が使用されていることを確認します (ミリ秒が予想される場合もあれば、プレーンな数値が必要な場合もあります)。

%%configure  
{  
"conf": {  
"spark.rpc.message.maxSize": "256",  
"spark.network.timeout": "800s",  
"spark.executor.heartbeatInterval": "60s"  
}  
}

シナリオ 2 - ClassNotFoundException

発生する理由:セッションの初期化中に必要なJava/Scala クラスが見つかりませんでした。 これは、カスタム JAR が存在しない、破損している、または別の Spark/Scala バージョン用にビルドされている場合に発生する可能性があります。

対処方法:

  • カスタム JAR を確認します。正しい Spark と Scala のバージョン (Spark 3.4/Scala 2.12 など) 用にコンパイルされていますか?

  • 最近環境にライブラリを追加した場合は、ライブラリを削除して再試行してください。

  • ドライバー ログで ClassNotFoundException を検索し、不足しているクラスを特定します。

  • 不足しているクラスが Spark/Fabric 内部 (org.apache.spark.*) に属している場合は再試行します。それでも解決しない場合は、サポートにお問い合わせください。

シナリオ 3 - UnknownHostException (一時的)

発生する理由: セッションの起動中の一時的な DNS 解決エラー。 クラスター リソース マネージャーに短時間到達できませんでした。

対処方法:

  • ジョブを再試行してください。 通常、このエラーは一時的なものであり、次の試行時に解決されます。

  • 同じ Spark プールで繰り返し発生する場合は、サポートにお問い合わせください。

シナリオ 4 - コンテナーの割り当てエラー

発生する理由: クラスターは、アプリケーションにコンテナーを割り当てることができませんでした。通常は、基になるインフラストラクチャのリソース不足が原因です。

対処方法:

  • 数分後にジョブを再試行します。

  • 同じプールで多数の同時実行セッションを実行している場合は、コンカレンシーを減らすか、プールをスケーリングしてみてください。

  • 複数の再試行でエラーが解決しない場合は、サポートにお問い合わせください。これは、インフラストラクチャの容量の問題を示している可能性があります。

ストレージと接続のエラー

ABFS StorageAccountDoesNotExist

エラー: Spark_Ambiguous_ABFS_StorageAccountDoesNotExist

発生する理由:指定したAzureストレージ アカウントが存在しないか、アクセスできません。

対処方法:

  • ストレージ アカウント名のスペルが正しいことを確認します。
abfss://<container>@<storage_account>.dfs.core.windows.net/<path>
  • Azure ポータルにストレージ アカウントが存在するかどうかを確認します (削除または名前が変更されている可能性があります)。

  • ストレージ アカウントが、Spark クラスターをブロックするファイアウォールの内側にないことを確認します。

  • アカウントに対する適切なアクセス許可 (ストレージ BLOB データ閲覧者/共同作成者) があることを確認します。

ABFS ストレージ操作に失敗しました

エラー: Spark_System_ABFS_OperationFailed

意味:Azure BLOB ファイル システム (ABFS) ストレージ操作に失敗しました。 これは通常、Spark コード エラーではなく、ストレージ接続、アクセス許可、またはネットワークの問題を示します。

発生する理由: プライベート リンクの設定に準拠していないため、要求が拒否されました。 これは、Spark が適切に構成されていないプライベート エンドポイントを介してストレージにアクセスしようとしたときに発生します。

対処方法:

  • ワークスペースのプライベート リンクとマネージド仮想ネットワーク設定が正しく構成されていることを確認します。

  • プライベート エンドポイントの DNS レコードがそのままであり、正しく解決されていることを確認します。

  • マネージド仮想ネットワークを使用している場合は、データ流出保護 (DEP) が一貫して有効になっていることを確認します。

シナリオ 2 — 403 承認/SAS エラー

発生する理由: 生成された SAS トークンまたは承認ヘッダーが無効であるか、有効期限が切れているため、403 Forbidden エラーが発生します。

エラー メッセージの例:

  • "サーバーが要求を認証できませんでした。 Authorization ヘッダーの値が正しく形成されていることを確認してください。

  • HTTP 403 での "AuthorizationPermissionMismatch"

対処方法:

  • ストレージ アカウントが最近キーまたはアクセス ポリシーを変更した場合は、Fabricワークスペース接続が更新されていることを確認します。

  • Lakehouse またはウェアハウスのショートカットに、有効な認証情報が設定されていることを確認してください。

  • サービス プリンシパルを使用している場合は、対象のストレージ アカウントに対して Storage Blob Data Contributor ロールが割り当てられていることを確認してください。

  • 再試行— トークン生成の問題は一時的なものになる可能性があります。

エラーにシステム ステージング パスに "AccessDeniedException" が含まれている場合 (たとえば、_system/artifacts/)、これは通常、プラットフォーム レベルの問題です。 最初に再試行します。解決しない場合は、サポートにお問い合わせください。

シナリオ 3 - ストレージ アカウントの接続

発生する理由: ファイアウォール規則、仮想ネットワークの制限、またはストレージ アカウントが別のリージョンに存在するため、Spark クラスターはストレージ アカウントに到達できません。

対処方法:

  • ストレージ アカウント ファイアウォールで "信頼されたMicrosoft サービス" からのアクセスが許可されていることを確認します。

  • プライベート エンドポイントを使用している場合は、ワークスペースの仮想ネットワーク内から DNS 解決を確認します。

  • ストレージ アカウントが存在し、削除または名前変更されていないことを確認します。

JDBC 接続に失敗しました

エラー: Spark_Ambiguous_JDBC_ConnectionFailed

発生する理由: 外部データベースへの JDBC 接続に失敗しました。

対処方法:

  • 接続パラメーター (ホスト、ポート、データベース名、ユーザー名、パスワード) を確認します。

  • Spark の外部(たとえば Python の pyodbc など)から接続テストを行い、問題が Spark にあるのかネットワークにあるのかを切り分けます。

  • ファイアウォール規則を確認する — データベースは Spark クラスターの IP 範囲からの接続を許可しますか?

  • データベース サーバーが実行され、接続を受け入れることを確認します。

  • JDBC ドライバーのバージョンの互換性を確認します。

JDBC SQLServerException

エラー: Spark_Ambiguous_JDBC_SQLServerException

発生する理由:JDBC 操作中にSQL Server固有のエラーが発生しました。

対処方法:

  • スタック トレースのSQL Serverエラー コードを読み取ります。
エラー コード Meaning 修正
18456 ログインに失敗しました ユーザー名/パスワードを確認する
233 接続が閉じられた ファイアウォール、サーバーの可用性を確認する
1205 デッドロックの被害者 操作を再試行します。並列処理を減らす
8115 算術オーバーフロー データ型と値を確認する
  • SQL Serverアクセス許可を確認します。ログインには適切な権限が必要です。

  • タイムアウト エラーの場合は、クエリのタイムアウトを増やします。

df = spark.read.format("jdbc") \
    .option("queryTimeout", "300") \
    .option("url", url) \
    .load()

ファイルとパスのエラー

FileInput — ファイルが見つかりません

このエラーは何を意味しますか? 「承認済みの標準 DCasV5/ECasv5 Family Cores クォータを超過することになるため、操作を完了できませんでした」

エラー コード Spark_User_FileInput_FileNotFoundは、指定したパスに存在しないファイルまたはディレクトリを Spark ジョブが読み取ろうとしたことを意味します。 これはユーザー エラーです。指定したパスが正しくないか、ファイルが削除されたか、まだ作成されていません。

確認すべきエラー メッセージ

org.apache.spark.sql.AnalysisException: Path does not exist: abfss://...

java.io.FileNotFoundException: No such file or directory

Input path does not exist: abfss://container@account.dfs.core.windows.net/...

一般的な原因と修正

パスが正しくないか、タイプミスがあります
  • 入力ミスがないか、コンテナー名、ストレージ アカウント、ファイル パスを再確認します。

  • NotebookUtils を使用してパスが存在するかどうかを確認します。

notebookutils.fs.ls("abfss://container@account.dfs.core.windows.net/folder/")
アップストリーム ジョブによってまだ作成されていないファイル
  • ノートブックが別のパイプラインまたはジョブからの出力に依存している場合は、このジョブが実行される前にアップストリーム ジョブが正常に完了したことを確認します。

  • パイプラインに依存関係またはチェックポイントを追加して、ファイルを待機します。

ファイルが削除または移動されました
  • アイテム保持ポリシー、クリーンアップ ジョブ、または別のユーザーがファイルを削除したかどうかを確認します。

  • Delta テーブルの場合は、トランザクション ログを調べて、VACUUM によってファイルが削除されたかどうかを確認します。

パーティション パスが存在しない
  • パーティション 分割されたデータを読み取る場合は、パーティション フィルターが既存のパーティションと一致していることを確認します。
df = spark.read.parquet("abfss://.../data/").where("date = '2024-01-15'")
  • 使用可能なパーティションを一覧表示します。
notebookutils.fs.ls("abfss://.../data/")
大文字小文字の区別
  • ABFS パスでは大文字と小文字が区別されます。 大文字と小文字が正確に一致していることを確認します。

SQL — PathDoesNotExist

このエラーは何を意味しますか? 「承認済みの標準 DCasV5/ECasv5 Family Cores クォータを超過することになるため、操作を完了できませんでした」

エラー コード Spark_User_SQL_PathDoesNotExistは、Spark SQL クエリが見つからないパス (テーブルの場所、ビュー、または外部データ ソース) を参照したことを意味します。 これは通常、テーブルの基になるストレージ パスが変更または削除されたときに発生します。

一般的な原因と修正

テーブルの基になるストレージが削除または移動されました
  • テーブル メタデータは、存在しなくなったパスを指します。 テーブルを再作成するか、その LOCATION を更新します。
-- Check the table location  
DESCRIBE EXTENDED schema_name.table_name

-- Recreate pointing to correct path  
CREATE TABLE schema_name.table_name USING DELTA LOCATION "abfss://..."
ワークスペースまたは Lakehouse の名前が変更されました
  • ワークスペースの名前を変更すると、ハードコーディングされたパスが壊れる可能性があります。 相対パスまたは notebookutils.fs を使用して、パスを動的に解決します。

Important

これは、Fabricに固有の一般的な実際のトラップです。 ワークスペースの名前を最近変更し、テーブルの動作が停止した場合は、これが原因である可能性があります。

正しいパスのないワークスペース間アクセス
  • 別のワークスペースのテーブルにアクセスする場合は、完全な ABFS パスを使用します。
spark.read.format("delta").load("abfss://container@account.dfs.core.windows.net/Tables/tablename")
ショートカットまたはマウント ポイントが壊れている
  • OneLake ショートカットを使用している場合は、ショートカット ターゲットがまだ存在し、接続が有効であることを確認します。

WASB — NoCredentials

Important

WASB (Windows Azure Storage BLOB) はレガシ プロトコルです。 主な修正は、abfss:// スキームを使用して ABFS (Azure BLOB ファイル システム) パスに移行することです。これは、Fabricで最新かつサポートされているアプローチです。 移行がすぐに不可能な場合にのみ、次の手順を使用します。

確認すべきエラー メッセージ

Spark_User_WASB_NoCredentials

No credentials found for account <storage_account>.blob.core.windows.net

WASB authorization failed

解決手順

1. ABFS に移行する (推奨)

  • パスを wasb[s]:// から abfss:// に変換します。
# Old (WASB): wasbs://container@account.blob.core.windows.net/path

# New (ABFS): abfss://container@account.dfs.core.windows.net/path

2. 移行できない場合は、ストレージ アカウント キーを構成します

spark.conf.set("fs.azure.account.key.<account>.blob.core.windows.net", "<key>")

Important

ノートブック コードにアカウント キーを格納することは、セキュリティ上のリスクです。 代わりにFabric接続またはAzure Key Vaultを使用してください。

認証とトークンのエラー

CustomTokenProvider が認証されていません

エラー: Spark_Ambiguous_CustomTokenProvider_Unauthorized

発生する理由: カスタム トークン プロバイダーで承認エラーが発生しました。

対処方法:

  • 認証資格情報が正しく、有効期限が切れていないことを確認します。

  • サービス プリンシパル/マネージド ID に必要なロールの割り当てがあることを確認します。

  • OAuth トークンの有効期限が切れていないことを確認します (実行時間の長いジョブがトークンの有効期間を上回る可能性があります)。

  • 特定の承認の失敗について、Microsoft Entra の監査ログを確認します。

セッション トークンを生成できない

エラー: UNABLE_TO_GENERATE_SESSION_TOKEN_WITH_TOKEN_PROVIDER

意味: Fabric Spark セッションを開始するために必要な認証トークンを生成できませんでした。 セッションは、ユーザー コードが実行される前に失敗します。

対処方法:

  • Fabric ワークスペースの容量がアクティブであり、一時停止されていないことを確認します。

  • Microsoft Entra テナントで認証の問題が発生していないことを確認します。

  • サービス プリンシパルまたはマネージド ID を使用している場合は、ワークスペースに正しいロールの割り当てがあることを確認します。

  • 新しいブラウザー セッションを開くか、キャッシュされた資格情報をクリアしてみてください。

  • エラーが断続的な場合は、再試行します。トークンの生成に一時的なエラーが発生する可能性があります。

  • 永続的な場合は、Fabric管理ポータルで容量またはテナント レベルの問題を確認してから、サポートにお問い合わせください。

ABFS 未承認 (403)

このエラーは何を意味しますか? 「承認済みの標準 DCasV5/ECasv5 Family Cores クォータを超過することになるため、操作を完了できませんでした」

エラー コード Spark_User_ABFS_Unauthorized は、Azure Blob File System (ABFS) ストレージにアクセスしようとした際に、Spark ジョブが 403 Forbidden 応答を受信したことを意味します。 ID エンティティまたはサービス プリンシパルには、必要なアクセス許可がありません。

確認すべきエラー メッセージ

Operation failed: "This request is not authorized to perform this operation using this permission."

StatusCode=403, ErrorCode=AuthorizationPermissionMismatch

StorageRequestFailedException: Status code: 403

一般的な原因と修正

Storage Blob Data ロールがありません
  • Fabric ID には、ストレージ アカウントに少なくともストレージ BLOB データ 閲覧者 (読み取り用) またはストレージ BLOB データ共同作成者 (書き込み用) が必要です。

  • Azure ポータルで、ストレージ アカウントに移動し、Access Control (IAM) を選択し、[ロールの割り当ての追加] を選択します。

SAS トークンの有効期限が切れているか、アクセス許可が不十分である
  • SAS トークンを使用している場合は、有効期限を確認し、適切なアクセス許可 (読み取り、書き込み、一覧) があることを確認します。
アクセスをブロックするファイアウォールまたはプライベート エンドポイント
  • ストレージ アカウントにファイアウォール規則がある場合は、Fabricワークスペースの IP 範囲が許可されていることを確認します。

  • Private Linkの場合は、プライベート エンドポイントが正しく構成され、承認されていることを確認します。

OneLake アクセスが正しく構成されていない
  • テナント間またはワークスペース間のアクセスの場合は、Fabric 管理者で共有設定とアクセス許可を確認してください。

トークン プロバイダーのユーザー エラー

このエラーは何を意味しますか? 「承認済みの標準 DCasV5/ECasv5 Family Cores クォータを超過することになるため、操作を完了できませんでした」

エラー コード TOKEN_PROVIDER_USER_ERRORは、Spark セッション用に構成されたトークン プロバイダーが、アクセス トークンを取得しようとしたときにエラーを返したことを意味します。 これにより、ジョブはダウンストリーム サービスに対して認証できなくなります。

一般的な原因と修正

サービス プリンシパルの資格情報の有効期限が切れている
  • サービス プリンシパルを使用している場合は、クライアント シークレットの有効期限が切れていないことを確認します。

  • Microsoft Entra IDでシークレットを更新し、Fabricで構成を更新します。

テナント、クライアント ID、またはクライアント シークレットが正しくありません
  • トークン プロバイダー構成の値が、Microsoft Entra ID アプリの登録と一致するかどうかを確認します。
  • サービス プリンシパルに必要な API アクセス許可が付与され、管理者の同意が提供されていることを確認します。
リンクされたサービスまたは接続が正しく構成されていません
  • Fabric接続またはリンクされたサービスを使用している場合は、それを再作成して接続をテストします。

Delta Lake とストリーミング エラー

DeltaLake DataTransformationException

エラー: Spark_Ambiguous_DeltaLake_DataTransformationException

完全なエラー コードには、Fabric固有のコードではなく、ユーザー アプリケーション例外クラス名が含まれる場合があります。

発生する理由: Delta Lake 操作のデータの処理中にデータ変換エラーが発生しました。

対処方法:

  • 完全なスタック トレースを調べます。通常は、失敗した特定の列または変換を識別します。

  • データ品質の問題を確認します: NULL を許可しない列の NULL 値、列の制約を超える値。

  • ソース データ スキーマがターゲットの Delta テーブル スキーマと一致するかどうかを確認します。

df.printSchema()  
spark.sql("DESCRIBE EXTENDED target_table").show(truncate=False)
  • 書き込み操作の前にデータ検証を追加します。
df = df.filter(col("required_col").isNotNull())  
df = df.withColumn("col_a", col("col_a").cast("expected_type"))

ストリーミング クエリの例外

エラー: Spark_Ambiguous_DeltaLake_org.apache.spark.sql.streaming.StreamingQueryException

発生する理由: Spark 構造化ストリーミング操作中に例外が発生しました。

対処方法:

  • 完全なスタックトレースを確認してください。そこには、実際の根本原因(OOM、ストレージエラー、スキーマ不一致)が隠れていることがあります。

  • ソースとシンクの可用性を確認します。

  • ストリーミング チェックポイントが有効でアクセス可能であることを確認します。

  • チェックポイントが破損している場合は、ストリームを最初から再起動する必要があります。

  • ストリーミング クエリ内の OutOfMemoryError については、「メモリの問題」セクションを参照してください。

アプリケーション コード エラー

UserApp NullPointerException

エラー: Spark_Ambiguous_UserApp_NullPointer

発生する理由: ユーザーのアプリケーション コードで NullPointerException が発生しました。

対処方法:

  • 完全なスタック トレースを読み取ります。null ポインターがコード内にあるか、Spark 内部コンポーネントにあるかを特定します。

  • 一般的な原因:

  • UDF に渡される DataFrame の列の NULL 値:

@udf(returnType=StringType())  
def safe_upper(x):  
    return x.upper() if x is not None else None
  • 処理する前に null をフィルター処理します。
df = df.filter(col("my_col").isNotNull())
  • Spark 変換内でシリアル化できないオブジェクトを参照しないようにします。

UserApp IllegalStateException

エラー: Spark_Ambiguous_UserApp_IllegalStateException

発生する理由: ユーザーのアプリケーション コードで IllegalStateException が発生しました。 無効なタイミングまたは無効な状態で操作が呼び出されました。

対処方法:

  • スタック トレースを読み取って、正確な場所を特定します。

  • spark.stop() mid-notebook を呼び出さないでください。

  • Spark タスク間で変更可能な状態を共有しないようにします。

  • Spark イテレータは一度しか走査できないため、再利用しないでください。

UserApp JobAborted

エラー: Spark_Ambiguous_UserApp_JobAborted

発生する理由: Spark ジョブが中止されました。通常、再試行を使い果たした後にステージが失敗したためです。

対処方法:

  • "SparkException: Job aborted" メッセージ内の原因を確認してください。このメッセージには実際のエラーが含まれています。

  • 一般的なラップされたエラー: TaskFailedException、FetchFailedException、FileNotFoundException。

  • Spark UI で、[ ステージ ] タブを選択し、失敗したステージを選択して、タスクの失敗の理由を確認します。

JVM 以外のユーザー アプリのエラー

エラー: Spark_Ambiguous_NonJvmUserApp_ExitWithStatus1、Spark_Ambiguous_NonJvmUserApp_FailedContainerLaunch

発生する理由:Python、R、またはその他の JVM 以外のアプリケーションの起動または終了に失敗し、エラーが発生しました。

対処方法:

  • ExitWithStatus1: ドライバー ログ (stderr) で、Python/R スタック トレース (SyntaxError、ModuleNotFoundError、および同様のエラー) を確認します。

  • FailedContainerLaunch: 互換性がない、または破損しているカスタム ライブラリ、またはリソースの制約。

  • まず、ローカルまたは最小限のノートブックでコードをテストします。

  • 問題を特定するには、カスタム ライブラリを 1 つずつ削除します。

UserApp ClassNotFound

このエラーは何を意味しますか? 「承認済みの標準 DCasV5/ECasv5 Family Cores クォータを超過することになるため、操作を完了できませんでした」

Spark_User_UserApp_ClassNotFoundエラー コードは、Spark ジョブがクラスパスに存在しない Java/Scala クラスを読み込もうとしたことを意味します。 これは通常、ライブラリが見つからない、インポートが正しくない、またはバージョンの不一致が原因で発生します。

一般的な原因と修正

JAR 依存関係が見つかりません
  • 必要な JAR をFabric環境にアップロードするか、セッションにアタッチします。
%%configure  
{"jars": ["abfss://container@account.dfs.core.windows.net/libs/my-lib.jar"]}
クラス名またはパッケージ パスが正しくありません
  • 完全修飾クラス名が、使用しているライブラリのバージョンと一致していることを確認します。
ライブラリのバージョンの不一致
  • クラスは、別のバージョンのライブラリに存在する可能性があります。 インストールされているバージョンを確認します。
# Check installed libraries  
spark.sparkContext.getConf().get("spark.jars")
Fat JAR が正しくビルドされていません
  • fat/uber JAR を使用する場合は、すべての推移的な依存関係が含まれていることを確認します。

  • JAR の内容を確認します。

# From a terminal  
jar tf my-app.jar | grep ClassName

NonJvmUserApp TypeError

このエラーは何を意味しますか? 「承認済みの標準 DCasV5/ECasv5 Family Cores クォータを超過することになるため、操作を完了できませんでした」

エラー コード Spark_User_NonJvmUserApp_TypeErrorは、PySpark コードで Python TypeError 例外が発生した場合を意味します。 これは、操作が不適切な種類のオブジェクトに適用されるときに発生します。

一般的な原因と修正

  • UDF の戻り値の型の不一致を確認します。UDF の戻り値の型注釈が、実際の戻り値の型と一致していることを確認します。

  • 結合、フィルター、集計などの操作の前に、DataFrame 列の種類を確認します。

  • 必要に応じ、明示的な型キャストを使用します。

from pyspark.sql.functions import col  
df = df.withColumn("amount", col("amount").cast("double"))
  • None/null 処理を確認します。PySpark UDF が null 値を受け取ると、処理されない場合にTypeErrorが発生する可能性があります。

UserApp KeyError

このエラーは何を意味しますか? 「承認済みの標準 DCasV5/ECasv5 Family Cores クォータを超過することになるため、操作を完了できませんでした」

エラー コード Spark_User_UserApp_KeyErrorは、PySpark コードが、通常は存在しないキーを持つディクショナリにアクセスするときに、Python KeyError 例外を発生させたことを意味します。

一般的な原因と修正

  • 直接ディクショナリ アクセスの代わりに既定値で .get() を使用します。
# Instead of: value = my_dict[key]  
value = my_dict.get(key, default_value)
  • 列名の変更を確認します。アップストリーム データ スキーマが変更された場合は、以前に有効なキーが存在しなくなる可能性があります。

  • UDF にエラー処理を追加します。

def safe_lookup(key):  
    try:  
        return lookup_dict[key]  
    except KeyError:  
        return None

UserApp AssertionError

このエラーは何を意味しますか? 「承認済みの標準 DCasV5/ECasv5 Family Cores クォータを超過することになるため、操作を完了できませんでした」

エラー コード Spark_User_UserApp_AssertionErrorは、コードが Python AssertionError を発生させた場合を意味します。 これは、assert ステートメントが失敗し、コードが true であると予想される条件が false であることを示す場合に発生します。

一般的な原因と修正

  • assert ステートメントを確認します。チェックされる条件は実行時に満たされません。
# This will raise AssertionError if df is empty  
assert df.count() > 0, "DataFrame is empty"
  • アサーションに依存するのではなく、適切なエラー処理を追加します。
if df.count() == 0:  
    raise ValueError("No data to process")
  • データ品質の問題を確認します。アサーションは、多くの場合、新しいデータで失敗する可能性があるデータ整合性の前提条件を保護します。

UserApp AttributeError

このエラーは何を意味しますか? 「承認済みの標準 DCasV5/ECasv5 Family Cores クォータを超過することになるため、操作を完了できませんでした」

エラー コード Spark_User_UserApp_AttributeErrorは、PySpark コードがオブジェクトに存在しない属性またはメソッドにアクセスしようとしたことを意味します。

一般的な原因と修正

  • Spark バージョン間の API の変更を確認します。Spark 3.3 に存在していたメソッドの名前が変更されたり、Spark 3.5 で削除されたりする可能性があります。 バージョン固有の破壊的変更については、 Spark SQL 移行ガイド を参照してください。

  • オブジェクトの種類を確認します。 一般的な間違いは、行、文字列、または None で DataFrame メソッドを呼び出すことです。

# Wrong: df.collect() returns a list, not a DataFrame  
result = df.collect()  
result.show() # AttributeError!  
  
# Correct:  
result = df.collect() # This is a list  
df.show() # Call show() on the DataFrame
  • None 値をチェックします。None オブジェクトでメソッドを呼び出すと AttributeError が発生します。

完全な DataFrame API リファレンスについては、「 PySpark DataFrame API」を参照してください。

ライブラリと環境のエラー

Conda PipFailed — ライブラリのインストールエラー

このエラーは何を意味しますか? 「承認済みの標準 DCasV5/ECasv5 Family Cores クォータを超過することになるため、操作を完了できませんでした」

エラー コード Spark_User_Conda_PipFailedは、Spark セッションの環境セットアップ中にライブラリのインストール (pip または conda 経由) が失敗したことを意味します。 Fabricは、構成に基づいてカスタム環境を作成します。このエラーは、そのセットアップが失敗したときに発生します。

一般的な原因と修正

パッケージが PyPI/Conda に存在しない

パッケージ名とバージョンが正しいことを確認します。

  • PyPI を確認します。 https://pypi.org/project/<package-name>/
  • または、ローカルで実行します。 pip install <package-name>==<version>
プレインストール済みパッケージとのバージョンの競合
  • Fabric環境には、プレインストール済みのパッケージが付属しています。 要求されたバージョンが競合する可能性があります。

  • プレインストールされているパッケージとそのバージョンの一覧については、Fabric ランタイムのリリース ノートを確認してください。

  • pip が互換性のあるバージョンを解決できるように、バージョン ピンを削除してみてください。

パッケージにはシステム レベルの依存関係が必要
  • 一部のPython パッケージには、Fabric環境で使用できない C ライブラリまたはシステム パッケージが必要です。

  • 可能な場合は、事前コンパイル済みのホイールを使用するか、純粋なPythonの代替手段を選択します。

ネットワーク接続の問題
  • プライベート エンドポイントまたはファイアウォールを使用している場合は、Fabric環境が PyPI またはプライベート パッケージ フィードに到達できることを確認します。
カスタム環境の構成エラー
  • 構文エラーについては、environment.ymlまたは requirements.txt を確認してください。

  • Fabricにデプロイする前に、ローカルで環境をテストします。

プラットフォームとエンジンのエラー

ネイティブ実行エンジン - InvalidState

エラー: Spark_System_NativeExecutionEngine_InvalidState

意味:Fabricネイティブ実行エンジンで内部エラーが発生し、クエリを処理できませんでした。 これはプラットフォーム レベルの問題であり、コード エラーではありません。

対処方法:

  • ジョブを再試行してください。一時的な無効な状態エラーは、多くの場合、次の実行時に解決されます。

  • エラーが再現可能な場合は、ネイティブ実行エンジンを無効にして、それが原因であることを確認してください。

%%configure  
{  
"conf": {  
"spark.native.enabled": "false"  
}  
}
  • ネイティブエンジンを無効にして問題が解決した場合は、クエリがサポートされていない特殊なケースに該当していたことを意味します。 サポートに問い合わせながら、回避策として無効にして実行します。

  • 完全なエラー メッセージと、それをトリガーしたクエリ/コードをサポート チケットに含めます。

Note

ネイティブ実行エンジンは、多くの一般的な操作を高速化しますが、すべての Spark SQL 機能をまだサポートしていません。 複雑な UDF、特定のデータ型、または通常とは異なるクエリ パターンは、標準の JVM エンジンにフォールバックしたり、失敗したりする可能性があります。

MetaStore — HiveException

エラー: Spark_System_MetaStore_HiveException

意味: Spark メタストア (Hive 互換カタログ) で、テーブルまたはデータベース操作の処理中にエラーが発生しました。

一般的な原因

原因 エラー スニペットの例
テーブル メタデータが破損しているか、見つからない HiveException: テーブルをフェッチできません...テーブルが見つかりません
同じテーブルでの DDL の同時実行 HiveException: ...ロックの取得がタイムアウトしました
互換性のないスキーマの進化 HiveException: テーブルを変更できません...列の種類が一致しません
カタログ接続のタイムアウト HiveException: ...接続拒否/読み取りタイムアウト

対処方法:

  • ジョブを再試行します。カタログ接続タイムアウトは一時的なことがよくあります。

  • 複数のノートブックから同じテーブルに対して同時実行 DDL (ALTER、DROP、CREATE) を実行しないようにします。

  • スキーマの変更が最近適用された場合は、テーブル スキーマを確認します。

DESCRIBE EXTENDED my_database.my_table
  • テーブルが破損している場合は、基になるデータから再作成してみてください。
-- For Delta tables  
CREATE TABLE my_table USING DELTA LOCATION 'abfss://...'  
  
-- For Parquet tables  
CREATE TABLE my_table USING PARQUET LOCATION 'abfss://...'
  • エラーに "ロックの取得" が示されている場合は、数分待ってから再試行します。別のセッションがメタデータ ロックを保持している可能性があります。

NotebookUtils EmptyString

エラー: Spark_Ambiguous_MsSparkUtils_EmptyString

発生する理由: notebookutils 関数は、値が必要な空の文字列を受け取りました。

対処方法:

  • notebookutils 関数に渡されるすべてのパラメーターが空でされていないことを確認します。

    # Incorrect  
    notebookutils.fs.ls("")  
    
    # Correct  
    notebookutils.fs.ls("abfss://container@account.dfs.core.windows.net/path")
    
  • 使用する前に、変数が初期化され、空でないものであることを確認します。

  • ノートブック パラメーターを使用する場合は、既定値が指定されていることを確認します。

サポートに連絡する時期

関連するセルフヘルプの手順を試しても問題が解決しない場合は、次のサポート チケットを開きます。

  • Spark アプリケーション ID (例: application_XXXXX_YYYY)

  • Spark UI またはドライバー ログからの正確なエラー コードとメッセージ

  • 完全なスタックトレース(ドライバーログの stderr からコピー)

  • Spark UI のスクリーンショット - [Executors] タブ、[ステージ] タブ、[ストレージ] タブ

  • Spark 構成 - ノード サイズ、ノード数、ランタイム バージョン、任意のカスタム spark.conf.set() 値

  • 処理されるおおよそのデータ サイズ

  • 問題が再現可能か、断続的か、新しいか (以前は機能していましたか?

  • データ、コード、環境、またはランタイム バージョンに対する最近の変更

  • エラーの原因となった SQL クエリまたはコード (該当する場合)

Spark アプリケーションの監視とインストルメント化の詳細については、「 Spark の監視とインストルメンテーション」を参照してください。