はじめに
Amplify Gen 2 の公式ドキュメントを見ながらチュートリアルを進めたのですが、いくつか素直には進まなかったポイントがありました。
この記事は、2025年5月時点で実際に詰まった点と、そのとき試して解決した内容のメモです。
公式ドキュメントに書かれていない点も含みますが、あくまで個人環境での記録なので、同じ症状でも原因が異なる場合があります。
対象のドキュメントはこちらです。
https://docs.amplify.aws/react/start/account-setup/
環境
- 実施時期: 2025年5月
- OS: Windows
- Node.js: v22.16.0
- npm: 9.0.0
- Amplify Gen 2 の React チュートリアルを実行
1. AWSアカウント登録で先に進めなかった
まず最初に、AWSアカウント登録の段階でつまずきました。
サインアップ画面でサーバーエラーが表示され、リクエストを完了できませんでした。
状況
- 大学のWi-Fi環境で登録を試していた
- 別回線に切り替えたところ登録できた
考えられる原因
大学Wi-Fi側のネットワーク制限、あるいは AWS 側でのアクセス判定が影響していた可能性があります。
対処
- 別のネットワーク回線で試す
- テザリングや自宅回線でも再試行する
補足
自分の環境では、大学のWi-Fiでは通らず、別回線では通ったので、回線依存を疑ってよさそうでした。
2. まず AWS CLI / SSO プロファイルを確認した
Amplify 側ではなく、先に AWS CLI 側の認証状態を確認しました。
aws sts get-caller-identity --profile default
これが成功したので、少なくとも SSO 経由の認証自体は通っていることが確認できました。
また、.aws/config に以下が正しく入っていることも確認しました。
sso_sessionsso_account_idsso_role_nameregion
Amplify のエラーが出ると Amplify 側を疑いたくなりますが、先に CLI の認証確認をしておくと切り分けしやすかったです。
3. npx ampx sandbox が「AWSアカウントを解決できない」系のエラーで失敗した
症状
npx ampx sandbox 実行時に、AWS アカウントを解決できない系のエラーが出て進めませんでした。
原因
自分の環境では、グローバルに入っていた CDK が古かったのが原因でした。
確認時の CDK バージョンは以下でした。
cdk --version
2.163.1
対処
古い CDK を削除して、最新に更新しました。
npm uninstall -g aws-cdk
npm install -g aws-cdk@latest
更新後、CDK は以下のようになりました。
2.1018.0
これで先に進めるようになりました。
4. npx ampx sandbox が could not determine executable で失敗した
症状
npx ampx sandbox 実行時に、could not determine executable のようなエラーが出ました。
原因
これは自分のミスで、npm で ダミーの ampx パッケージを入れてしまっていました。
対処
間違って入れたものを削除して、Amplify の CLI を入れ直しました。
npm uninstall -g ampx
npm install -g @aws-amplify/backend-cli
ampx という名前だけを見て入れるとハマるので、ここは地味に注意ポイントでした。
5. ampx sandbox --once が package.json を見つけられなかった
症状
ampx sandbox --once を実行したときに、package.json が見つからない形で失敗しました。
原因
コマンドを実行していた場所が、プロジェクトルートではありませんでした。
自分は別フォルダで実行していました。
対処
正しいディレクトリへ移動してから再実行しました。
cd C:\Users\user\Downloads\AWS\amplify-vite-react-template
基本的なことですが、エラーが派手だと別原因に見えてしまうので、実行場所の確認は早めにやった方がよかったです。
6. ampx sandbox --once が CDK エラー（ENOENT）で失敗した
症状
ampx sandbox --once が CDK 関連の ENOENT で失敗しました。
考えられる原因
このときは、node_modules が壊れていたか、依存関係が不足していた可能性がありました。
対処
いったん依存関係を削除して、入れ直しました。
Remove-Item -Recurse -Force node_modules
Remove-Item -Force package-lock.json
npm install
依存まわりを再構築したあと、再度 ampx sandbox --once を試しました。
7. @aws-amplify/backend が見つからず TypeScript エラーになった
症状
以下のエラーが出ました。
Cannot find module '@aws-amplify/backend' or its corresponding type declarations.
原因
Amplify のバックエンド機能に必要な開発用モジュールである @aws-amplify/backend が入っていませんでした。
対処
以下で追加しました。
npm install --save-dev @aws-amplify/backend
これでこのエラーは解消しました。
8. TypeScript の型エラーも出た
症状
以下のような型エラーも出ました。
Parameter 'allow' implicitly has an 'any' type.
原因
TypeScript の strict 設定下で、コールバック引数の型が明示されていないのが原因でした。
応急処置
とりあえず型を明示して回避しました。
authorization((allow: any) => [allow.owner()])
または、一時的に tsconfig.json で strict: false にする方法もあります。
ただし、strict: false は影響範囲が広いので、応急処置として使うなら注意した方がよさそうです。
9. hotswap fallback 警告はエラーではなかった
途中で以下のようなメッセージも出ました。
Could not perform a hotswap deployment... Falling back to doing a full deployment
最初は失敗かと思ったのですが、これは エラーではありませんでした。
意味
一部リソースが hotswap に対応していないため、通常の CloudFormation デプロイに切り替わった、という意味でした。
対応
特に対処不要でした。
初回デプロイや構成変更時には、通常デプロイに切り替わるのは普通のようです。
最終的な成功条件
最終的に、自分の中では以下を成功条件にしました。
-
ampx sandbox --onceが成功する - プロジェクトルートに
amplify_outputs.jsonが出力される
実行時には、以下のように npm_config_user_agent を設定していました。
$env:npm_config_user_agent="npm/9.0.0 node/v22.16.0 win32 x64"
ampx sandbox --once
ここまで通れば、サンドボックス構築は完了と判断してよさそうでした。
まとめ
Amplify Gen 2 の公式チュートリアル自体は追いやすいのですが、実際には次のような点で詰まりました。
- AWS アカウント登録時のネットワーク依存
- AWS CLI / SSO 認証確認の切り分け
- 古い CDK による不整合
-
ampxパッケージの取り違え - 実行ディレクトリのミス
-
node_modules/ 依存関係の破損や不足 -
@aws-amplify/backendの未導入 - TypeScript の型エラー
-
hotswap fallbackをエラーと勘違いすること
同じように npx ampx sandbox や ampx sandbox --once 周りで止まった人の参考になればと思います。
おわりに
Amplify Gen 2 は便利そうだったのですが、最初のセットアップ時点では思ったよりハマりどころがありました。
特に、「認証は通っているのに sandbox が失敗する」 みたいなケースは切り分けがしづらかったです。
今後また別の箇所で詰まったら、追記するか別記事に分けようと思います。