フォアグラウンド サービスのトラブルシューティング

このページでは、フォアグラウンド サービスが失敗する一般的な理由と、問題の原因を特定する方法について説明します。

このドキュメントでは、次の問題について説明します。

トラブルシューティングの前に

フォアグラウンド サービスに対する最近の変更を確認する

フォアグラウンド サービスを不適切に使用すると、デバイスのパフォーマンスやバッテリー駆動時間に悪影響を及ぼす可能性があります。そのため、Android プラットフォームのリリースでは、こうした悪影響を抑えるために、フォアグラウンド サービスの動作が変更されることがよくあります。

フォアグラウンド サービスで問題が発生している場合は、フォアグラウンド サービスの変更 に関するドキュメント を確認し、問題の原因となる可能性のある最近の変更がないかどうかを確認してください。特に、次のような状況では変更を確認することが重要です。

  • 以前は機能していたフォアグラウンド サービスのコードが機能しなくなった
  • 新しいプラットフォーム リリースでのテストを開始したばかりであるか、アプリのターゲット API レベルを変更した

また、プラットフォームのデベロッパー プレビューでデバイスをテストしている場合は、デベロッパー プレビュー ドキュメントの最新バージョンを確認してください。

アプリケーション応答なし（ANR）エラー

状況によっては、アプリがフォアグラウンド サービスをシャットダウンすることが想定されます。アプリがサービスを停止しない場合、システムがサービスを停止し、アプリケーション応答なし（ANR）エラーが発生します。

短いサービスが長時間実行され、ANR が発生する

短いサービス タイプを使用するフォアグラウンド サービスは、約 3 分以内に完了する必要があります。時間が経過すると、 システムはサービスの Service.onTimeout(int,int) メソッドを呼び出します。サービスは 、stopSelf() を呼び出すまでに数秒かかります。サービスが自動的に停止しない場合、システムはアプリケーション応答なしエラーを発生させます。

診断:

フォアグラウンド サービスが自動的に停止しなかったために ANR が発生した場合、システムは内部例外をスローします。ANR レポートを確認することで、これが問題であったことを確認できます。これが問題の場合、レポートには次のメッセージが含まれます。

Fatal Exception: android.app.RemoteServiceException: "A foreground service of
type FOREGROUND_SERVICE_TYPE_SHORT_SERVICE did not stop within its timeout:
[component name]"

解決方法:

時間制限のあるすべてのフォアグラウンド サービスが作業を完了し、 stopForeground(int)システムの時間制限内に呼び出すようにします。

フォアグラウンド サービスに Service.onTimeout(int,int) を実装します。 そのメソッドの実装で stopSelf() がすぐに呼び出されるようにします。

フォアグラウンド サービスの例外

このセクションでは、システムが例外をスローする原因となるフォアグラウンド サービスの問題について説明します。アプリが例外をキャッチしない場合、アプリが停止したことを示すダイアログがユーザーに表示されます。

場合によっては、システムが内部例外をスローすることがあります。このような場合は、スタック トレースで例外の内容を確認し、Logcat で詳細なエラー情報を確認できます。

内部例外: タイムアウトを超過した

システムには、アプリがバックグラウンドにある間、データ同期とメディア 処理のフォアグラウンド サービスが実行できる時間の上限があります。サービスがその上限を超えると、システムはサービスの Service.onTimeout(int,int) メソッドを呼び出します。サービスは、stopSelf() を呼び出すまでに数秒かかります。サービスが自動的に停止しない場合、システムは内部 RemoteServiceException を生成してアプリをクラッシュさせます。

診断:

スタック トレースで例外の内容を確認し、Logcat で詳細なエラー情報を確認できます。この場合、Logcat には次のエラー メッセージが表示されます。

Fatal Exception: android.app.RemoteServiceException: "A foreground service of
type [service type] did not stop within its timeout: [component name]"

解決方法:

時間制限のあるすべてのフォアグラウンド サービスが作業を完了し、システムの時間制限内に stopForeground(int) を呼び出すようにします。

フォアグラウンド サービスに Service.onTimeout(int,int) を実装します。 そのメソッドの実装で stopSelf() がすぐに呼び出されるようにします。

内部例外: ForegroundServiceDidNotStartInTimeException

`context.startForegroundService()` を呼び出してサービスを起動すると、そのサービスは `ServiceCompat.startForeground()` を呼び出してフォアグラウンド サービスに昇格するまでに数秒かかります。サービスが昇格しない場合、 は内部 ForegroundServiceDidNotStartInTimeException をスローします。

診断:

スタック トレースで例外の内容を確認し、Logcat で詳細なエラー情報を確認できます。この場合、Logcat には次のエラー メッセージが表示されます。

android.app.RemoteServiceException$ForegroundServiceDidNotStartInTimeException:
Context.startForegroundService() did not then call Service.startForeground()

解決方法:

新しく作成されたすべてのフォアグラウンド サービスが数秒以内に ServiceCompat.startForeground() を呼び出すようにします。

WorkManager:

フォアグラウンド サービスを実行する（setForegound または setForegroundAsync を呼び出す）WorkManager ワーカーでも、この例外が発生することがあります。2 つのフォアグラウンド ワーカーのライフサイクルが重複し、以前に実行されていたフォアグラウンド サービスがシャットダウンしようとしているときに、1 つのワーカーがフォアグラウンド サービスを開始しようとすると、このクラッシュが発生し、次のログが記録されます。

Re-initializing SystemForegroundService after a request to shut-down

このクラッシュの修正は、 WorkManager バージョン 2.10.5で導入されました。

アプリで この例外が発生する場合は、WorkManager の最新バージョンに更新し、解決しない 問題は WorkManager の Issue Tracker に報告してください。

ForegroundServiceStartNotAllowedException

エラー:

システムが ForegroundServiceStartNotAllowedException をスローします。

原因:

これは通常、有効な除外がない場合に、アプリがバックグラウンドからフォアグラウンド サービスを起動することが原因で発生します。

Android 12（API レベル 31）以降では、アプリがバックグラウンドで実行されている間、少数の特定の除外を除いて、フォアグラウンド サービスを起動することはできません 。バックグラウンドからフォアグラウンド サービスを開始しようとして、除外の要件を満たしていない場合、システムは ForegroundServiceStartNotAllowedException をスローします。除外の要件を満たしていない場合も同様です。

たとえば、アプリにユーザーがクリックできるボタンがあり、そのボタンをクリックすると、アプリが何らかの処理を行ってからフォアグラウンド サービスを起動するとします。この場合、ユーザーがボタンをクリックしてすぐにアプリをバックグラウンドに置く可能性があります。アプリはバックグラウンドからサービスを起動しようとします。アプリが指定された除外のいずれかを満たしていない場合、システムは ForegroundServiceStartNotAllowedException をスローします。

また、一部の除外には短い時間制限があります。たとえば、アプリが高優先度の FCM メッセージに応答してフォアグラウンド サービスを起動する場合、短い免除があります。サービスを迅速に起動しないと、ForegroundServiceStartNotAllowedException が発生します。

特定の除外は、新しい Android リリースで制限が厳しくなることがあります。アプリのターゲットとする Android のバージョンを変更した場合は、フォアグラウンド サービスの変更に関するドキュメントを確認し、アプリが許可されている除外のいずれかを満たしていることを確認してください。

解決方法:

アプリがバックグラウンドにある間にフォアグラウンド サービスを起動する必要がないようにアプリのワークフローを変更するか、アプリが除外のいずれかを満たしていることを確認します。

ライフサイクル対応コンポーネントを使用すると、 アプリのライフサイクルを管理できるため、バックグラウンドからフォアグラウンド サービスを誤って起動しようとすることがなくなります。

SecurityException

エラー:

システムがSecurityExceptionをスローします。

原因:

アプリが必要な権限を持たずにフォアグラウンド サービスを起動しようとしました。

  • アプリが Android 9（API レベル 28）以降をターゲットとしている場合、フォアグラウンド サービスを起動するには FOREGROUND_SERVICE 権限が必要です。
  • アプリが Android 14（API レベル 34）以降をターゲットとしている場合は、フォアグラウンド サービス タイプのすべての前提条件を満たす必要があります。これらの前提条件については、 フォアグラウンド サービス タイプのドキュメントで詳しく説明しています。特に、次の要件に注意してください。
    • 一部のフォアグラウンド サービス タイプでは、特定のランタイム権限が必要です。たとえば、リモート メッセージング フォアグラウンド サービスには FOREGROUND_SERVICE_REMOTE_MESSAGING 権限が必要です。
  • 一部のフォアグラウンド サービス タイプに必要な権限には、使用中の制限が追加されている場合があります。これらの権限は アプリがフォアグラウンドにある場合にのみアプリに付与されます（少数の 特定の例外を除く）。つまり、アプリがこれらの権限のいずれかをリクエストして付与された場合でも、アプリがバックグラウンドにある間にフォアグラウンド サービスを起動しようとすると、アプリがバックグラウンドからフォアグラウンド サービスを起動する除外がある場合でも、システムは SecurityException をスローします。詳細については、 使用中の権限が必要なフォアグラウンド サービスの起動に関する 制限をご覧ください。
    • 必要な権限をリクエストしたが、必要な権限が付与されたことを確認する前にフォアグラウンド サービスを開始すると、SecurityException が発生する可能性があります。

解決方法:

フォアグラウンド サービスを起動する前に、適切なフォアグラウンド サービスの権限をすべてリクエストし、他のランタイムの前提条件をすべて満たしていることを確認します。