トラブルシューティング

このトラブルシューティングガイドは、Amplify CLI を使用して構築されたアプリケーションの開発、デプロイ、および移行中に発生する一般的なエラーを検出および修正するためのガイダンスを開発者に提供します。

必読事項

すべての Amplify CLI プロジェクト向け

デプロイメント の問題をデバッグするために、Amplify によって生成されたプロジェクトのファイル構造と Amplify CLI によって生成されたアーティファクトを理解することが役に立ちます。

1. Amplify CloudFormation アーティファクト: Amplify CLI は CloudFormation テンプレートと CLI ウォークスルー中にユーザーが提供する入力パラメータを使用して AWS リソースをプロビジョニングします。Amplify CLI バージョン 7 以上では、一部のカテゴリ (Storage、Auth、API) により、開発者は Amplify CLI Overrides 機能を使用して Amplify で生成された AWS リソース構成をオーバーライドできます。

2. Amplify CLI ウォークスルー入力パラメータアーティファクト: CLI ウォークスルー中にユーザーが提供したすべての入力は、/amplify/backend フォルダ内の JSON ファイルに保存されます。たとえば、cli-inputs.json または amplify-meta.json。これらのファイルを使用して、開発者が提供した構成と Amplify で生成された構成の両方を検査して、潜在的な問題の根本原因を特定できます。Amplify バックエンドファイルドキュメントを参照して、ファイルが手動で編集しても安全かどうかを確認してください。

Amplify CLI が init、publish、push の実行時にリクエストするドメイン。

プロキシを介して Amplify CLI を実行する場合は、以下のドメインをホワイトリストに追加してください。

• amazonaws.com
• amplifyapp.com
• aws-amplify.github.io

GraphQL API を備えた Amplify CLI プロジェクト向け

GraphQL API を備えたプロジェクトのデプロイメント の問題をデバッグするために、GraphQL プロジェクトで Amplify によって生成されたさまざまなアーティファクトを理解することが役に立ちます。

1. GraphQL スキーマ VTL 生成: Amplify CLI GraphQL ワークフローは AWS AppSync サービスを使用して GraphQL API をプロビジョニングします。amplify api gql-compile コマンドは開発者が提供した GraphQL スキーマをトランスパイルし、AWS に API をデプロイするために必要なすべてのアーティファクトを生成します。
   • GraphQL スキーマ内の @model、@function、@auth、@searchable などのディレクティブは CloudFormation を生成し、AWS リソースをプロビジョニングするために使用されます。
   • クエリ、ミューテーション、またはサブスクリプションの GraphQL リゾルバーは VTL (Velocity Template Language) ファイルに変換されます。AWS AppSync は VTL を使用して、クライアントからの GraphQL リクエストをデータソースへのリクエストに変換します。
2. GraphQL スキーマクライアント側コード生成: Amplify CLI GraphQL ワークフローにより、開発者は amplify codegen コマンドを使用して Web とモバイルクライアント用のクライアント側コードを生成できます。クライアント側のコード生成の問題をデバッグする前に、Amplify コード生成ドキュメントを参照してください。

「amplify push」 エラーのトラブルシューティング

amplify push コマンドは以下のステップを実行します:

1. リソースを AWS にデプロイするための CloudFormation を生成します。
2. アプリケーションに GraphQL API が含まれている場合、CLI は内部で amplify api gql-compile を実行してスキーマをコンパイルし、マッピングリゾルバーと AWS リソースを割り当てるための CloudFormation テンプレートの VTL (Velocity Templates) を生成します。
3. デプロイメントアーティファクトをビルド、パッケージ化し、アプリケーションのデプロイメントバケットにアップロードします。
4. AWS CloudFormation SDK を使用して CloudFormation スタックを AWS アカウントにデプロイします。
5. リソースを AWS に正常にデプロイした場合、Amplify CLI はデプロイメントバケット内のデプロイメントパッケージの名前を #current-cloud-backend.zip に変更します。このファイルはデプロイメントの信頼できる情報源です。
6. ローカルプロジェクトが削除または破損した場合は、amplify pull を使用して常に最後の正常なデプロイメントに戻すことができます。

** これは Amplify デプロイメントバケット内の重要なファイルとフォルダを示しています **

** 以下のセクションでは、異なるタイプの「amplify push」エラーの例と推奨される解決策を含めています **

クラウドリソースへの非管理変更によるプッシュエラー - ドリフト

AWS コンソールを使用する場合など、Amplify の外部から Amplify で生成されたリソースへの変更は「非管理変更」と呼ばれます。Amplify CLI は、Amplify で生成された CloudFormation スタックの外部で行われた変更を追跡できません。CloudFormation での予期された資源の構成と実際のサービス構成間のこの相違は「CloudFormation ドリフト」と呼ばれます。現在、CloudFormation ドリフトを自動的に逆転させる方法はありません。各リソースは AWS コンソール経由で CloudFormation スタック内のドリフトについて検査され、ドリフトを手動で解決する必要があります。

デプロイ時、Amplify で生成された CloudFormation テンプレートは AppSync GraphQL API と複数の DynamoDB テーブルを GSI とともにプロビジョニングします。

シナリオ 1: コンソールから DynamoDB テーブルと GSI を手動で更新した後、「amplify push」が失敗する。

GraphQL スキーマがクラウドにデプロイされているアプリケーションがあると想定します。Amplify は GraphQL スキーマ内のすべての @model 型に対して DynamoDB テーブルを作成し、すべての @index フィールドに対して GSI を作成します。Amplify CLI を使用する代わりに DynamoDB コンソール を使用して GSI を削除する場合、「ドリフト」が導入されます。ドリフトが存在すると、GraphQL スキーマへの今後の変更はデプロイに失敗する可能性があります。たとえば、GraphQL スキーマ内の一部の @model 型と @index フィールドの名前を変更して amplify push --allow-destructive-graphql-schema-updates コマンドを実行する場合、Amplify は最初に元のモデル名に対応するすべての DynamoDB テーブルを削除します。ただし、これらのテーブルの GSI がすでにコンソールから手動で削除されている場合、デプロイメントは失敗します。これは、Amplify の CloudFormation スタックが存在しないリソース (GSI) の状態を更新しようとしているためです。

推奨される解決策: DynamoDB テーブルのドリフトによるデプロイメント エラーを修正するには、ドリフトしたリソースの状態を CloudFormation の状態と一致するように手動でロールバックします。その後、amplify push を再試行します。

1. AWS ドリフト検出ドキュメントの指示に従って、DynamoDB CloudFormation スタック内のドリフトを表示できます。
2. AWS コンソール経由で各ドリフトを手動で戻します。この特定のシナリオでは、GSI を再作成し、手動で名前変更の変更を元に戻します。
3. amplify push を実行します。

シナリオ 2: クラウド内の非データベースリソースへの非管理更新後、「amplify push」が失敗する。

Amplify CLI を使用してクラウドにデプロイされた GraphQL スキーマを持つアプリケーションがあると想定します。その後、以下のタイプの変更を 1 つ以上実行しました

1. AppSync コンソールを使用して GraphQL スキーマを更新した、または
2. Cognito コンソールから Amplify によって作成されたユーザープールを削除した、または
3. 元々 Amplify を通じてデプロイされた Lambda 関数のコードを更新しました。これらのタイプの非管理変更は、影響を受けるリソースのドリフトを導入します。したがって、Amplify を使用したこれらのリソースへの後続の更新はほぼ確実にデプロイメント失敗につながります。

推奨される解決策: これらのタイプのドリフトはケースバイケースで対処する必要があります。Lambda コード変更などの場合によっては、コードへの軽微な変更を行って関数の再デプロイメントを強制することが機能する可能性があります。ユーザープールの削除や AppSync コンソールから GraphQL スキーマへの更新などの他の場合は、以下の手順に従います:

1. 新しい CloudFormation スタックデプロイメントを強制する - amplify push --force を実行してアプリケーションのリソースをプッシュを強制します。
2. CloudFormation コンソールから CloudFormation スタックのプッシュを強制する - アプリケーションのデプロイメントバケット内の「amplify-cfn-templates」フォルダから CloudFormation スタックを取得し、(AWS CloudFormation - スタック更新ドキュメント)に記載されている CloudFormation コンソール経由でスタックをセレクティブに更新します。
3. ドリフト変更をコードに適用する - 上記の方法が失敗した場合、もう 1 つのオプションは手動変更を検査し、CLI 入力ファイルで更新することです。たとえば、GraphQL スキーマを更新してクラウド内で手動で実行した同じ変更を反映させ、amplify push を実行できます。

マルチアカウントマルチ環境プロジェクトでのプッシュエラー (CI/CD エラー)

マルチアカウントプロジェクトで CI/CD を使用する場合、アプリケーションは 1 つのアカウントで正常にデプロイされたにもかかわらず、別のアカウントではデプロイメント が失敗しています。以下は一般的な原因です:

1. Amplify で生成された CloudFormation で参照されている一部のリソースが失敗したアカウントから欠落しています。
2. 失敗したアカウントが CloudFormation で使用されている特定のリソースにアクセスするためのアクセス許可がありません。
3. アプリケーションコードが失敗した環境で正しく作成またはコピーされていない「シークレット」に依存しています。

シナリオ 1: 「amplify push」が 1 つのアカウント/環境で失敗する

「dev」アカウントでプロジェクトを作成し、デプロイメント 環境を dev、beta、prod 環境を備えた完全な CI/CD パイプラインに拡張したと想定します。プロジェクトはおそらく Amplify CLI チーム環境ガイドで指定されたパターンに従います。すべてのステップが完了すると、Amplify ホスティングコンソールは「beta」などの環境の「build」ステップを失敗と表示し、他の環境を正常にデプロイされたものとして表示しています。

推奨される解決策: Amplify CLI を使用して失敗したアカウントにアプリケーションをデプロイします。上記の場合、dev 環境は正常にデプロイされていますが、beta 環境は失敗しています。まず、dev 環境から App ID を取得します。Amplify コンソールでアプリケーションの dev 環境の「Edit backend」セクションで App ID を見つけることができます。以下のステップを実行して、dev 環境からアプリを取得し、beta 環境にデプロイします。

1. amplify pull --appId <YOUR_APP_ID> --envName dev
2. amplify env checkout beta
3. amplify push

amplify push が失敗する場合、CloudFormation イベントログで失敗したリソースを確認して、失敗した環境の問題を修正するための詳細情報を取得します。AWS CloudFormation コンソールでアプリケーションのスタック名を検索します。たとえば、アプリケーションに「lil」という名前を付けて「dev」環境にデプロイした場合、Amplify は amplify-lil-dev-{random chars} という名前の CloudFormation スタックを生成します。CloudFormation コンソールでアプリケーションのスタック名をクリックしてから、「Resources」タブをクリックします。「Resources」タブはスタック内のすべてのリソースのデプロイメント ステータスを表示します。デプロイメント エラー理由も表示されます。CloudFormation トラブルシューティングドキュメントを参照してエラーメッセージの詳細を確認してください。

注: シークレットが環境間で正しくコピーされていないことに関連する問題をデバッグするには、アクセスシークレット値ドキュメントの マルチ環境フローセクションを参照してください。

AWS サービスクォータを超過することによるプッシュエラー

AWS は様々な AWS サービスの サービスクォータを管理しています。アプリケーションに多くのリソース (多くのリゾルバーを持つ大規模な GraphQL スキーマまたは多くの REST API など) が含まれている場合、サービス制限に達する可能性があります。AWS Service レベルのクォータを超えることがデプロイメント エラーを引き起こしたかどうかを特定するには、CloudFormation デプロイメント/失敗ログについて AWS コンソールを確認してください。

推奨される解決策:

1. アプリケーションのリソース要件が AWS サービスクォータによって影響を受ける場合は、AWS Service Quotas コンソールを使用してほとんどの AWS クォータの表示とリクエスト増加を実行できます。
2. Amplify DataStore を使用している場合は、Amplify DataStore ベストプラクティスを参照して、正しい設計判定を行い、アプリケーション内のリソース割り当てを最適化するための洞察を確認してください。
3. サービスクォータを増加できない場合は、サーバーレス環境で持続可能なスケーリングのためにアプリケーションの一部の側面を再設計する必要があります。AWS Knowledge Centerを参照することで、異なる推奨設計変更の理解に役立つ可能性があります。たとえば、複雑な GraphQL スキーマを簡略化して使用中の GraphQL リソース数を減らすことができます。例:スキーマを書き直してモデルを減らす。overrides および export などのエスケープハッチを使用することで、CLI によって生成されたアーキテクチャを超えてアプリケーションをスケーリングするのに役立つ可能性があります。

シナリオ 1: ポリシー数を削減するための REST API スキーマの最適化:

Amplify CLI を使用して多くのルートを持つ REST API をデプロイし、すべてのルートを処理する 1 つの Lambda 関数を持つと想定します。この場合、Amplify CLI はルートごとに 1 つのポリシーを生成し、Lambda 実行ロールに適用します。したがってこの構成では、許可されるルートの最大数は AWS IAM 制限の「Max policies per role」制限によって制限されます。次のテーブルはこのような構成のルートに関連するポリシーの分布を示しています。 注: 「Resource」は API Gateway resource「Route」を処理するために割り当てられた項目を表します。

ただし、アプリケーションに多くのルートがある場合、生成されるポリシー数を減らす 1 つの方法は、単一のルートリソースを作成し、追加のパスをクエリパラメータとしてサポートすることです: /items?item=rock, /items?item=paper, /items?item=scissors この場合、Amplify CLI は /items リソースに対して 1 つのポリシーのみを作成します。

GraphQL スキーマ構文エラーによるプッシュエラー

GraphQL スキーマを変更した後は、amplify api gql-compile を実行してスキーマが有効であり、Amplify が GraphQL スキーマから正しい CloudFormation テンプレートを生成できることを確認してください。Amplify CLI GraphQL ドキュメントを参照して、最新の Amplify GraphQL ディレクティブを理解してください。

シナリオ 1: GraphQL スキーマエラー

GraphQL スキーマに「@model」ディレクティブが「@mode」と誤って綴られているエラーがあると想定します:

type Tag @mode { /** @mode is an invalid directive **/
  id : ID!
  tag: String
  topics: [Topic]
}

amplify api gql-compile を実行するとき、変換ステップは無効なディレクティブエラーで失敗します。

GraphQL スキーマ関連のその他のエラーのトラブルシューティング

amplify push が以下のシナリオのいずれかをデプロイ中に失敗する場合は、Amplify GraphQL トラブルシューティングガイドを参照してください。

1. 単一の amplify push で複数のインデックス変更をデプロイ
2. DynamoDB テーブルから OpenSearch インデックスをバックフィル
3. 複数のソートキーフィールドを持つインデックス

「amplify pull」 エラーのトラブルシューティング

大量の UI コンポーネントによるプルエラー

v12.2.0 以降、Amplify CLI は amplify pull 中の UI コンポーネント生成に対応可能なタイムアウトを導入しました。デフォルトではこのタイムアウトは 2 分に設定されていますが、UI_BUILDER_CODEGENJOB_TIMEOUT 環境変数を使用してタイムアウトを増加できます。

例えば、タイムアウトを 5 分 (300000ms) に増加したい場合

export UI_BUILDER_CODEGENJOB_TIMEOUT=300000
amplify pull

「Failed to get profile credentials」のトラブルシューティング

AWS IAM Identity Center (以前の AWS SSO) を使用していて、以下のエラーが表示される場合、credential_process ワークアラウンドが不足している可能性があります

🛑 Failed to get profile credentials
Cannot read properties of undefined (reading 'accessKeyId')

Learn more at: https://docs.amplify.aws/cli/project/troubleshooting/

「Unexpected token A in JSON at position 0」

AWS IAM Identity Center (以前の AWS SSO) を使用していてこのエラーが表示される場合、このエラーは Amplify CLI ワークフロー内で AWS プロファイルのプロンプトが表示されたときに sso-session エントリを選択することによって引き起こされる可能性があります。これが発生した場合、以前のコマンドを再実行し、関連する SSO プロファイルを選択します。

デプロイメント ベストプラクティス

このセクションでは、開発者が Amplify プロジェクトのデプロイメント エラーとスケーリング問題を回避するのに役立つ様々なベストプラクティスについて説明しています。

Amplify CLI デフォルト動作のオーバーライド

アプリケーションへの変更は Amplify CLI と関連する構成ファイル経由、または Amplify Studio 経由でのみ実行する必要があります。明確に記載されている場合を除き、AWS コンソールまたは AWS CLI/SDK を使用してリソースを直接手動で編集してはいけません。Amplify CLI コマンド内で利用可能なカスタマイズを超えて Amplify で生成されたリソースをオーバーライドするには、Amplify 拡張性ドキュメントの指示に従う必要があります。このドキュメントは Amplify CLI で利用可能なすべての「エスケープハッチ」について詳しく説明しています。

GraphQL スキーマ内のモデル名変更の影響の理解

Amplify は GraphQL スキーマで @model ディレクティブで注釈が付けられた GraphQL 型に対して DynamoDB データベーステーブルを自動的に作成します。したがって、GraphQL スキーマ内のモデルの名前を変更する場合、アプリケーションデータの誤削除から保護するために、Amplify CLI は後続の amplify push 操作をブロックし、--allow-destructive-graphql-schema-updates フラグを明示的に渡すように促します。このフラグは、DynamoDB テーブルの削除など、データベースへの破壊的な変更を行う Amplify CLI の機能を許可します。これは元のモデル名用のテーブルを削除し、スキーマで指定された新しいモデル名のテーブルを新規作成します。Amplify は現在、自動データ移行をサポートしていません。元のテーブルのデータが必要な場合は、DynamoDB テーブルをバックアップし、新しいテーブルの破壊的なデプロイメント後にデータを移行する必要があります。

GraphQL トランスフォーマー V1 から V2 への移行

GraphQL トランスフォーマー V1 を使用してアプリケーションを以前にデプロイし、GraphQL トランスフォーマー V2 への移行を決定した場合は、更新する前に、GraphQL トランスフォーマー移行ドキュメントを参照してスキーマディレクティブと制限への移行の影響を理解してください。amplify status コマンドを使用してGraphQL トランスフォーマーのバージョンを確認できます。また、${project-root}/amplify/cli.json 内の transformerversion 機能フラグを検査して確認することもできます。

バージョン 11: AWS CDK V1 から V2 への移行

Amplify CLI バージョン 11.0.0 より前にデプロイされたかつ、overrides またはカスタムリソースを使用する Amplify プロジェクトの場合は、AWS CDK 移行ドキュメントを参照してください。問題が解決しない場合は、issue を作成してください

CDK v2 への移行の詳細を確認してください

ローカルテスト

デプロイメント 前に、スキーマ変更とビジネスロジックができるだけ多くテストしてください。amplify mock コマンドを使用すると、クラウド依存関係をローカルで検証できます。Advanced workflows ドキュメントの mock テスト例に従ってさらに詳しく確認してください。

さらに詳しく知る

サポートに連絡する

GitHub で同様の問題を検索するか、新しい issue を開きます

• amplify-cli issues
• amplify-codegen issues

AWS Enterprise support と連絡を取ります

コミュニティ Discord チャネルに参加します