1.はじめに
1.1.まえがき
本ブログは以下項目の4つに分かれており、本ブログはその4つ目になります。
※ 本ハンズオンの全コードはこちらのGitHubリポジトリで参照できます。
1.2.今回の内容
本シリーズ最後は、ハンズオン中に実際に遭遇したエラーとその解決方法まとめます。
- CDK設定関連エラー：7個（構文・設定・権限含む）
- IAM権限関連エラー：2個
- Docker/ECR関連エラー：2個
- Bootstrap関連エラー：4個
1.3.本ブログでの構成図
1.4.デバッグの基本アプローチ
- エラーが発生した場合、以下の観点で確認をしていきました。
- エラーメッセージの確認：正確なエラー文を取得
- 実行環境の確認：どこで（GitHub Actions/ローカル/CloudShell）発生したかの調査
- 依存関係の確認：前後のステップの確認
- リソース状態の確認：AWS各サービスの状態を確認
2.カテゴリ別トラブルシューティング
2.1.CDK設定関連エラー
2.1.1.エラー名：cdk.json: Unexpected token / in JSON at position … (GitHub Actions)
| 事象 |
詳細 |
| 現象 |
cdk deploy 実行時に JSON 構文エラーが発生。 |
| 原因 |
cdk.json ファイル内に JSON で許可されていないコメント (// …) が含まれていた。 |
| 対策 |
cdk.json ファイルからコメントを削除。 |
2.1.2.エラー名：Unsupported feature flag ‘@aws-cdk/core:enableStackNameDuplicates’ (GitHub Actions)
| 事象 |
詳細 |
| 現象 |
cdk deploy 実行時にサポートされていない機能フラグのエラーが発生。 |
| 原因 |
cdk.json の context に、CDK v1 用の古い機能フラグが含まれていた。 |
| 対策 |
cdk.json の context から @aws-cdk/core:enableStackNameDuplicates の行を削除。 |
2.1.3.エラー名：Source image …:latest does not exist. (GitHub Actions – CloudFormation)
| 事象 |
詳細 |
| 現象 |
CloudFormation が Lambda 関数を作成しようとして、ECR イメージ :latest が見つからないエラーが発生。 |
| 原因 |
GitHub Actions から CDK へイメージタグ (コミットハッシュ) が環境変数経由で正しく渡されず、CDK コード側でデフォルトの :latest が使われてしまっていた。 |
| 最終的な対策 |
GitHub Actions の cdk deploy コマンドで -c image_tag=<タグ> のように CDK Context を使ってイメージタグを渡し、CDK コード側も self.node.try_get_context("image_tag") で受け取るように修正することで解消。 |
2.1.4.エラー名：SyntaxError: ‘(‘ was never closed (GitHub Actions)
| 事象 |
詳細 |
| 現象 |
cdk deploy の Synth 段階で Python 構文エラーが発生。 |
| 原因 |
pipeline_stack.py のコード修正時に括弧の閉じ忘れがあった。 |
| 対策 |
エラー箇所 (lambda_.DockerImageFunction の定義) の括弧の対応を確認し、修正。 |
2.1.5.エラー名：AccessDenied: … ssm:GetParameter on resource: …/cdk-bootstrap/…/version (GitHub Actions)
| 事象 |
詳細 |
| 現象 |
cdk deploy 実行時に SSM パラメータへのアクセス拒否エラーが発生。 |
| 原因 |
GitHub Actions の IAM ロール (GitHubAction-AssumeRoleWithAction) に、CDK Bootstrap のバージョン情報を読み取る権限がなかった。 |
| 対策 |
GitHubAction-AssumeRoleWithAction ロールに AmazonSSMReadOnlyAccess ポリシー（またはより限定的な ssm:GetParameter 権限）をアタッチ。 |
2.1.6.エラー名：AccessDenied: … cloudformation:DescribeStacks on resource: …/CDKToolkit/* (cdk bootstrap 実行時)
| 事象 |
詳細 |
| 現象 |
SageMaker ターミナルから cdk bootstrap を実行しようとして権限エラーが発生。 |
| 原因 |
SageMaker の実行ロールに CloudFormation を操作する権限がなかった。 |
| 対策 |
管理者権限を持つユーザーで CloudShell から cdk bootstrap を実行する。 |
2.1.7.エラー名：TypeError: Code.from_ecr_image() got an unexpected keyword argument ‘image_uri’ (GitHub Actions)
| 事象 |
詳細 |
| 現象 |
cdk deploy の Synth 段階で from_ecr_image の引数エラーが発生。 |
| 原因 |
from_ecr_image に存在しない image_uri パラメータを指定していた。 |
| 対策 |
正しいパラメータ repository と tag_or_digest を使うように修正。 |
2.2.IAM権限関連エラー
2.2.1.エラー名：AccessDenied: … sts:AssumeRole on resource: …/cdk-…-file-publishing-role-… (GitHub Actions)
| 事象 |
詳細 |
| 現象 |
cdk deploy 実行時に、CDK Bootstrap が作成したファイル公開用ロールへの Assume Role 権限がないエラーが発生。 |
| 原因 |
GitHubAction-AssumeRoleWithAction ロールに、Bootstrap ロール群への sts:AssumeRole 権限がなかった。 |
| 対策 |
Bootstrap ロール群への sts:AssumeRole を許可するカスタム IAM ポリシーを作成し、GitHubAction-AssumeRoleWithAction ロールにアタッチ。 |
2.2.2.エラー名：AccessDenied: … iam:PassRole on resource: …/cdk-…-cfn-exec-role-… (GitHub Actions)
| 事象 |
詳細 |
| 現象 |
cdk deploy 実行時に、CloudFormation 実行ロールへの PassRole 権限がないエラーが発生。 |
| 原因 |
GitHubAction-AssumeRoleWithAction ロールに、CloudFormation 実行ロールへの iam:PassRole 権限がなかった。 |
| 対策 |
CloudFormation 実行ロールへの iam:PassRole を許可するカスタム IAM ポリシーを作成し、GitHubAction-AssumeRoleWithAction ロールにアタッチ（または既存のカスタムポリシーに追加）。 |
2.3.Docker/ECR関連エラー
2.3.1.エラー名：Cannot find asset at /path/to/app (GitHub Actions)
| 事象 |
詳細 |
| 現象 |
lambda_.Code.from_asset() または DockerImageCode.from_image_asset() で指定したアセットパスが見つからない。 |
| 原因 |
cdk deploy の実行ディレクトリ (working-directory: ./cdk) から見たアセット (app ディレクトリ) への相対パス指定が間違っていた (../../app ではなく ../app が正しかった)。 |
| 対策 |
pipeline_stack.py 内のパス指定を正しい相対パス ("../app") に修正。 |
2.3.2.エラー名：Failed to build asset … (ビルド成功直後) (GitHub Actions)
| 事象 |
詳細 |
| 現象 |
Docker イメージビルド成功のログ直後にアセットビルド失敗のエラーが発生。-vvv でも詳細不明。 |
| 原因 |
IAM/ECRリポジトリポリシー/Docker認証など複合的な要因が考えられたが特定困難。 |
| 最終的な対策 |
CDK Assets の利用をやめ、GitHub Actions で明示的に docker build & docker push を行い、CDK では lambda_.Code.from_ecr_image() でプッシュ済みのイメージタグを参照する方式に変更することで解消。 |
2.4.Bootstrap関連エラー
2.4.1.エラー名：SSM parameter …/cdk-bootstrap/…/version not found. Has the environment been bootstrapped? (GitHub Actions)
| 事象 |
詳細 |
| 現象 |
cdk deploy 実行時に Bootstrap バージョン情報が見つからないエラーが発生。 |
| 原因 |
デプロイ対象のアカウント・リージョンで cdk bootstrap が実行されていなかった。 |
| 対策 |
CloudShell など適切な権限を持つ環境から cdk bootstrap を実行。 |
2.4.2.エラー名：S3 … Bucket … already exists (cdk bootstrap 実行時)
| 事象 |
詳細 |
| 現象 |
cdk bootstrap 実行時に S3 バケットが既に存在するためエラーが発生。 |
| 原因 |
以前の Bootstrap が不完全に終了した、または手動で同名バケットが作成されていた。 |
| 対策 |
CloudFormation コンソールで CDKToolkit スタック (もし失敗状態で存在すれば) を削除し、S3 コンソールで該当バケットを削除してから、再度 cdk bootstrap を実行。 |
2.4.3.エラー名：No module named aws_cdk.cli (GitHub Actions)
| 事象 |
詳細 |
| 現象 |
pip install -r requirements.txt で aws-cdk-lib をインストールしたにも関わらず、python -m aws_cdk.cli deploy … を実行するとモジュールが見つからない。 |
| 原因 |
Python のバージョン不整合（actions/setup-python と仮想環境作成時の Python バージョンが異なっていた）、または GitHub Actions 環境における Python パッケージ認識の問題と想定。 |
| 最終的な対策 |
Python のバージョンを統一 (3.10) し、仮想環境を作成・有効化して実行しても解決せず。最終的に Node.js ベースの CDK CLI (npm install -g aws-cdk と cdk deploy …) を使う方式に変更することで解消。 |
2.4.4.エラー名：handler must be Handler.FROM_IMAGE when using image asset… (GitHub Actions)
| 事象 |
詳細 |
| 現象 |
lambda_.Function + Code.fromasset を使用した Lambda 関数のデプロイ時にエラー発生。コード上は handler=lambda.Handler.FROM_IMAGE が指定されているにも関わらず発生。 |
| 原因 |
CDK CLI と aws-cdk-lib のバージョン不一致、または CDK/JSII の内部的なバグの可能性が高い (GitHub Issue #25758 でも類似報告あり)。 |
| 最終的な対策 |
lambda_.DockerImageFunction クラスを使用するようにコードを書き換えることで解消。 |
3.おわりに
3.1.得られた知見
- IAM 権限 (OIDC, AssumeRole, PassRole, 各サービスへのアクセス) の設定が重要。
- CDK Assetsの処理は便利だが、特定困難なエラーが発生した場合は、Actions 側でビルド/プッシュしたりと回避策を考えることも必要。
- cdk bootstrap は CDK デプロイの前提条件であり、対象アカウント・リージョンごとに一度実行が必要。実行に必要な権限や、既存リソースとの競合にも注意が必要。
deploy.ymlで、エラーメッセージを出力させながらなにがどうなっている状態を管理して、トラブルシュートしていく。
3.2.今後の課題
- 今回付与した IAM ポリシー (FullAccess 系やカスタムポリシー) の見直し、最小権限の原則に従ったものに修正する。
- CDK Assets の Docker イメージ処理で発生した Failed to build asset エラーの根本原因を特定。
- API Gateway や Lambda 関数の監視（CloudWatch Logs, Metrics, Alarms）を CDK で設定し、デプロイ後の構成管理を行うこと。
- テストコード (ユニットテスト、インテグレーションテスト) を導入し、CI/CD パイプラインに組み込むことで、デプロイの信頼性を向上させること。
3.3.終わりのコメント
この4回に渡るハンズオンシリーズを通して、Lambdaコンテナを使ったモダンなCI/CDパイプラインを構築してきました。
多くのエラーに遭遇しましたが、それぞれの解決プロセスこそが実践的なスキルに繋がっていくのだと思います(ほぼLLMが提案してくれたとはいえ)。
皆さんのプロジェクトでも同様のエラーに遭遇した際は、本トラブルシューティング集が解決の一助となれば幸いです。
最後までお読みいただき、ありがとうございました。
