◀戻る

ネイティブイメージの実行時エラーのトラブルシューティング

事前コンパイルが成功しても、実行時にクラッシュしたり、Java VM上でのアプリケーションの動作と異なる動作をするイメージが生成される場合があります。このガイドでは、その理由と、問題を診断および解決するための戦略を示します。

GraalVMの最新バージョンにアップグレードするだけで問題が解決する場合があることに注意してください。

1. メタデータ登録の欠落を診断する

最初に、メタデータ設定が欠落しているかどうかを診断します。ネイティブイメージでは、使用されるすべてのクラスがビルド時に認識されている必要があります。静的解析は、アプリケーションの実行時の動作を予測しようとします。場合によっては、すべての動的機能呼び出しを解析で認識できるように、設定を提供する必要があります。設定を提供しないと、アプリケーションで動的機能が使用されると、実行時に診断が困難なエラーで終了するイメージが生成されます。これは、欠落しているメタデータを事前にチェックすることで回避できます。

  1. native-imageツールに--exact-reachablity-metadataオプションを渡して、アプリケーションを再ビルドします。特定のパッケージに対してのみこれを実行する場合は、パッケージプレフィックス--exact-reachablity-metadata=[パッケージプレフィックス]を指定します。

    このオプションは、JDK 23 用の GraalVM で導入され、次の機能リリースでデフォルトになります。これは、-H:ThrowMissingRegistrationErrors=ホストオプションと同等です。

  2. 次に、-XX:MissingRegistrationReportingMode=Warnオプションを渡してネイティブ実行可能ファイルを実行し、登録が欠落しているコード内のすべての場所を見つけます。

  3. 欠落しているメタデータが報告された場合は、必ず*reachability-metadata.json*ファイルに追加してください。その方法については、到達可能性メタデータのドキュメントを参照してください。

  4. 次に、-XX:MissingRegistrationReportingMode=Exitを使用してネイティブ実行可能ファイルを再起動し、アプリケーションが誤って欠落している登録エラーを無視している場所（catch (Throwable t)ブロックを使用）を検出します。アプリケーションは、スタックトレースを含むエラーメッセージを無条件に出力し、すぐに終了します。この動作は、すべてのメタデータが含まれていることを保証するためのアプリケーションテストを実行するのに最適です。

共有ライブラリ

ネイティブイメージでビルドされた共有ライブラリを診断するには、次のいずれかを実行できます。

  • ネイティブ共有ライブラリをビルドするときに-R:MissingRegistrationReportingMode=Exitを指定します。
  • または、分離環境が作成されたときに-XX:MissingRegistrationReportingMode=Exitを指定します。 graal_create_isolate_params_tには、実行時にCスタイルのコマンドラインオプションを渡すために使用できるargc (_reserved_1)およびargv (_reserved_2)フィールドがあります。ただし、両方のフィールドは現在パブリックAPIではないことに注意してください。

2. java.homeを明示的に設定する

アプリケーションコードで`java.home`プロパティを使用する場合は、ネイティブ実行可能ファイルを実行するときに`-Djava.home=<パス>`を使用して明示的に設定します。設定しない場合、`System.getProperty("java.home")`呼び出しは`null`値を返します。

3. URLプロトコルを有効にする

ビルド時にオンデマンドですべてのURLプロトコルを有効にしてみてください：`--enable-url-protocols=<プロトコル>`。 HTTPSサポートのみを有効にするには、`--enable-https`を渡します。

4. シグナル処理を有効にする

アプリケーションがシグナル処理または`java.lang.Terminator`終了ハンドラーを使用している場合は、ビルド時に`--install-exit-handlers`オプションを指定します。

5. すべての文字セットとロケールを含める

その他の便利なオプションは、文字セットのサポートを追加する`-H:+AddAllCharsets`と、`java.util`および`java.text`パッケージのロケール依存の動作のサポートを事前に初期化する`-H:+IncludeAllLocales`です。ビルド時にこれらのオプションを渡します。これにより、結果のバイナリのサイズが大きくなる可能性があります。

6.不足しているセキュリティプロバイダーを追加する

アプリケーションがセキュリティプロバイダーを使用している場合は、ビルド時に`-H:AdditionalSecurityProviders=<プロバイダーのリスト>`オプションを渡すことにより、セキュリティプロバイダーを事前に初期化してみてください。選択できるすべてのJDKセキュリティプロバイダーのリストは次のとおりです。`sun.security.provider.Sun,sun.security.rsa.SunRsaSign,sun.security.ec.SunEC,sun.security.ssl.SunJSSE,com.sun.crypto.provider.SunJCE,sun.security.jgss.SunProvider,com.sun.security.sasl.Provider,org.jcp.xml.dsig.internal.dom.XMLDSigRI,sun.security.smartcardio.SunPCSC,sun.security.provider.certpath.ldap.JdkLDAP,com.sun.security.sasl.gsskerb.JdkSASL`。

7. ネイティブイメージの実行時に関する問題を報告する

上記のすべての提案を試しても解決しない場合にのみ、GitHubでネイティブイメージの実行時に関する問題レポートを提出してください。必要な情報を記入してください。

適切で実用的なチケットを提出するために必要な情報を収集するには、診断モードを有効にして`native-image`ビルドを実行することをお勧めします。クラスの初期化、置換などの診断出力を有効にする`--diagnostics-mode`オプションを渡します。

お問い合わせ