よくある DynamoDB エラー（と修正方法）
開発者が最もよく遭遇する DynamoDB エラー。それぞれの意味、原因、正確な修正方法を解説します。
検証と式のエラー (52)
DynamoDB ValidationException — 原因と修正方法
DynamoDB の ValidationException は、リクエストが形式不正として実行前に拒否されたことを意味します。よくあるきっかけ、読むべきメッセージ、そしてそれぞれの直し方。
"Query condition missed key schema element" — DynamoDB の修正
Query condition missed key schema element は、KeyConditionExpression にパーティションキーの等価条件がないことを意味します。代わりに GSI をクエリするか、Scan を使いましょう。
"The provided key element does not match the schema" — DynamoDB の修正
この ValidationException は、キー属性の名前や型がテーブルの KeySchema と一致しないことを意味します — ソートキーの欠落や、文字列として送られた数値が原因です。
"Invalid UpdateExpression" Syntax Error — DynamoDB の修正
Invalid UpdateExpression の原因はたいてい、予約語を素で使ったことか、#name / :value プレースホルダーの欠落です。メッセージの読み方と直し方を解説します。
"ExpressionAttributeValues contains invalid value" — DynamoDB の修正
この ValidationException は、ExpressionAttributeValues 内の値が空、誤った型、または式で定義していないプレースホルダーであることを意味します。
"Item size has exceeded the maximum allowed size" — DynamoDB の修正
DynamoDB のアイテムは 400 KB が上限です。この ValidationException はアイテムが上限を超えていることを意味します — サイズの確認方法と、上限内に戻す方法を解説します。
DynamoDB ConditionalCheckFailedException — 原因と修正
ConditionalCheckFailedException は、ConditionExpression が false と評価されたため、DynamoDB が書き込みを拒否し、アイテムを変更しなかったことを意味します。
DynamoDB TransactionCanceledException — キャンセル理由の読み解き方
TransactionCanceledException は、1 つのアイテムが失敗してトランザクション全体がロールバックされたことを意味します。CancellationReasons 配列を読めば、どのアイテムがなぜ失敗したか分かります。
DynamoDB SerializationException — 原因と修正
SerializationException は、送った JSON が DynamoDB のワイヤーフォーマットと一致しないことを意味します — 多くは数値を文字列で包んだ場合です。型付き AttributeValue のラッパーを直しましょう。
"Supplied AttributeValue is empty" — DynamoDB の修正
この ValidationException は、AttributeValue が型付きの値を持たないことを意味します — 空のセット、空のキー文字列、未定義のフィールドです。削除するか、値を設定しましょう。
"One or more parameter values were invalid" — DynamoDB の修正
この ValidationException は、ある値が DynamoDB のルールを破ることを意味します — 空のセット、空のキー文字列、型の不一致です。メッセージがどのパラメータかを示します。
"Invalid size for parameter" — DynamoDB ベクトル書き込みの修正
埋め込みの次元数がベクトルインデックスと一致しないとき、DynamoDB はベクトルの書き込みを拒否します。メッセージは属性名と両方のサイズを示します。
"Search vector contains invalid values" — DynamoDB の修正
SearchVectors は、DynamoDB の L 型で包まれたクエリベクトルや、float 以外の値を含むクエリベクトルを拒否します。このパラメータは List 属性ではなく、裸の JSON 配列です。
"SearchConditionExpression must be provided" — DynamoDB の修正
HASH 検索スキーマキーを持つベクトルインデックスは、すべての SearchVectors 呼び出しに、ちょうど 1 つのパーティション値の固定を要求します。フィルターは、インデックス作成の時点で任意ではなくなりました。
"Query key condition not supported" — DynamoDB の修正
DynamoDB は、キースキーマが許さない演算子を使う KeyConditionExpression を拒否します — パーティションキーは等価比較しか受け付けません。使える演算子を一覧します。
"Attribute name is a reserved keyword" — DynamoDB の修正
DynamoDB は status、name、size のような予約語を素の属性名として使うことを拒否します。#status のような ExpressionAttributeNames のプレースホルダーでエイリアス化しましょう。
"Float types are not supported" — DynamoDB boto3 の修正
DynamoDB は正確な 10 進数を保存するため、boto3 は TypeError "Float types are not supported" を発生させます。float は文字列形式を経由して decimal.Decimal に変換しましょう。
"Number overflow" — DynamoDB の数値サイズ制限の修正
DynamoDB の N 型が保持できるのは 38 桁の精度と約 9.9E+125 までの大きさです。それを超える大きな ID や高精度の値は、代わりに文字列として格納しましょう。
"The provided expression refers to an attribute that does not exist" — 修正
UpdateExpression または ConditionExpression が、アイテムに存在しないパスを参照しています。欠落した親マップ、タイプミス、または欠落した属性に対する演算が原因です。
"Provided list of item keys contains duplicates" (BatchGetItem) — 修正
DynamoDB は、あるテーブルの Keys リストにプライマリキーが重複している BatchGetItem を拒否します。バッチ全体が失敗するため、送信前にキーを重複排除しましょう。
"Provided list of item keys contains duplicates" (BatchWriteItem) — 修正
DynamoDB は、2 つの操作が同じプライマリキーを対象とする BatchWriteItem を拒否します。1 つのバッチが同じアイテムを 2 回操作することはできないため、重複をまとめましょう。
"Expression size has exceeded the maximum allowed size" (4 KB) — 修正
DynamoDB はすべての式文字列を 4 KB に制限します。FilterExpression、ConditionExpression、UpdateExpression がそれを超えると拒否されます。縮小する方法を解説します。
"Aggregated size of all range keys has exceeded the size limit" — 修正
DynamoDB はソートキーを 1024 バイト、パーティションキーを 2048 バイトに制限します。この ValidationException の背後にあるサイズの計算と、キーの直し方を解説します。
"Filter Expression can only contain non-primary key attributes" — 修正
DynamoDB は、パーティションキーやソートキーを参照する FilterExpression を拒否します。キーは KeyConditionExpression に属します — クエリの組み立て直し方を解説します。
DynamoDB BatchGetItem の100アイテム上限 — "Too Many Items" の修正
BatchGetItem が 1 回の呼び出しで扱えるのは最大 100 アイテム（かつ 16 MB）です。それ以上を要求すると DynamoDB はリクエスト全体を拒否します。制限と、チャンク分割のループ。
"Too many items requested for the BatchWriteItem call" — 修正
BatchWriteItem が 1 回の呼び出しで受け付けるのは最大 25 件の put または delete アクションです。それ以上を送ると DynamoDB は ValidationException でリクエスト全体を拒否します。
DynamoDB "Can Not Use Both Expression and Non-Expression Parameters" — 修正
DynamoDB は、KeyConditions のようなレガシーパラメータと KeyConditionExpression を混在させたリクエストを拒否します。レガシーパラメータを削除し、式だけを使いましょう。
"Local secondary indexes must be specified at table creation" — 修正
ローカルセカンダリインデックスはテーブル作成時にしか定義できず、後から追加することはできません。この制約が存在する理由と、その回避方法を解説します。
DynamoDB TransactionCanceledException — ConditionalCheckFailed の修正
TransactWriteItems が ConditionalCheckFailed でキャンセルされたのは、あるアイテムの条件が失敗し、トランザクション全体がロールバックされたことを意味します。その特定方法を解説します。
"Value provided in ExpressionAttributeNames unused in expressions" — 修正
DynamoDB は、どの式からも参照されない ExpressionAttributeNames のエイリアスを宣言したリクエストを拒否します。削除するか、参照し忘れた式を直しましょう。
"Value provided in ExpressionAttributeValues unused in expressions" — 修正
DynamoDB は、どの式も使わない ExpressionAttributeValues のプレースホルダーを宣言したリクエストを拒否します。余った値を削除するか、式を直しましょう。
DynamoDB S3 Import Failed — Invalid Format の修正
DynamoDB の S3 からのインポートは、オブジェクトが宣言した InputFormat や圧縮と一致しないとき、あるいはアイテムにプライマリキーがないとき失敗します。その直し方を解説します。
"Size of hashkey has exceeded the maximum size limit of 2048 bytes" — 修正
DynamoDB のパーティションキーは最大 2048 バイト、ソートキーは最大 1024 バイトです。いずれかを超えると書き込みは拒否されます — キーの再設計方法を解説します。
DynamoDB GSI "Does Not Project" Attribute — 修正
GSI が返すのはキー属性とその投影だけなので、それ以外を求めるクエリは失敗します。投影かリクエストを変えましょう — その方法を解説します。
"Nesting Levels have exceeded supported limits" — DynamoDB 32 レベルの修正
DynamoDB はマップとリストのネストを 32 レベルに制限します — それより深いドキュメントは "Nesting Levels have exceeded supported limits" をスローします。フラット化の方法。
"Segment must be less than TotalSegments" — 並列スキャンの修正
並列 Scan は 0 ≤ Segment < TotalSegments を満たし、両方を一緒に渡すことを要求します。各ワーカーには 0 から TotalSegments − 1 までの異なる Segment を割り当てましょう。
DynamoDB "Cannot Specify AttributesToGet When Select Is COUNT" — 修正
DynamoDB は、Select=COUNT を ProjectionExpression や AttributesToGet と併用した Query や Scan を拒否します。COUNT は数値を返すだけなので、プロジェクションを外しましょう。
DynamoDB Streams "The ARN provided is invalid" — 修正
DynamoDB Streams は、不正な形式や /stream/latest のようなプレースホルダーのストリーム ARN を拒否します。DescribeTable が返す本物の LatestStreamArn をそのまま渡しましょう。
"Transaction request cannot include multiple operations on one item" — 修正
DynamoDB は、2 つのアクションが同じプライマリキーを対象とする TransactWriteItems の呼び出しを拒否します。重複をまとめるか、片方を別の書き込みに移しましょう。
DynamoDB TransactWriteItems の100アクション上限 — 修正
TransactWriteItems の上限は 100 アクションで、それを超えると TransactItems の長さに対する ValidationException が返ります。分割するか、1 回 25 件の BatchWriteItem を使いましょう。
DynamoDB TTL Attribute Must Be a Number — 原因と修正
DynamoDB の TTL が期限切れにできるのは、TTL 属性が Unix エポック秒の Number であるアイテムだけです。文字列、ミリ秒値、属性の欠落では決して期限切れになりません。
DynamoDB "The expression can not be empty" — 修正
DynamoDB は、式パラメータを空文字列として渡すと拒否します。送るものがないときは FilterExpression や UpdateExpression を丸ごと省略しましょう。
"ExpressionAttributeNames contains invalid key: Syntax error" — 修正
DynamoDB は、プレースホルダーキーが `#name` 構文を破る ExpressionAttributeNames マップを拒否します。命名ルールと、本当の属性名を書く場所を解説します。
"Two document paths overlap with each other" (DynamoDB) — 修正
DynamoDB は、親のパスとその内側にネストしたパスの両方を設定する UpdateExpression を拒否します。子を親にまとめるか、2 回の更新に分けましょう。
"The document path provided in the update expression is invalid" — 修正
ドキュメントパスが無効なのは、ネストした属性の親が存在しないか、マップではないためです。DynamoDB が自動で作ることはないので、先に親を作成しましょう。
"An operand in the update expression has an incorrect data type" — 修正
更新オペランドの型が格納された属性と一致しません — 非数値への ADD、非リストへの list_append、一致しないセット型などです。アクションごとの直し方を解説します。
DynamoDB IdempotentParameterMismatchException — 原因と修正
TransactWriteItems は、10 分間の冪等性ウィンドウ内で ClientRequestToken を異なるペイロードで再利用したリトライを拒否します。その直し方を解説します。
"Consistent reads are not supported on global secondary indexes" — 修正
ConsistentRead を true にして GSI をクエリすると ValidationException が発生します。GSI は結果整合性のある読み込みしか提供しません。フラグを外すか、ベーステーブルを読みましょう。
DynamoDB DuplicateItemException (PartiQL INSERT) — 原因と修正
PartiQL の INSERT は、プライマリキーがすでに存在すると DuplicateItemException で失敗します。PutItem と違って上書きしないため、UPDATE か PutItem を使いましょう。
"Unexpected from source" (DynamoDB PartiQL) — 修正
PartiQL は、ダッシュなどの特殊文字を含むテーブル名が FROM でダブルクォートされていないとき "Unexpected from source" をスローします。ダブルクォート 1 組で解決します。
boto3 "Parameter validation failed" (ParamValidationError) — 修正
botocore は、リクエストが DynamoDB に届く前に ParamValidationError を発生させます — たいていは client と resource の型の取り違えです。読み方と直し方を解説します。
"The provided starting key is invalid" (DynamoDB) — 修正
DynamoDB は、ページングしているテーブルやインデックスのキースキーマと一致しない ExclusiveStartKey を拒否します。LastEvaluatedKey をそのまま渡し、手作りしないでください。
スループットとスロットリングのエラー (11)
DynamoDB ProvisionedThroughputExceededException — 原因と修正
DynamoDB は、読み取りや書き込みがテーブルまたは GSI のプロビジョニング済みキャパシティを超えると ProvisionedThroughputExceededException をスローします。何が枯渇したのかと、その直し方。
DynamoDB ThrottlingException — 原因と修正
ThrottlingException は、リクエストレートが制限を超えたことを意味します。多くは CreateTable のようなコントロールプレーンの呼び出しです。指数バックオフで再試行し、頻度を下げましょう。
DynamoDB ItemCollectionSizeLimitExceededException — 原因と修正
このエラーはローカルセカンダリインデックスを持つテーブルでのみ発生します — アイテムコレクション（1 つのパーティションキーを共有する全アイテム）が 10 GB を超えました。その直し方。
DynamoDB RequestLimitExceeded — 原因と修正
RequestLimitExceeded はアカウントレベルのレート制限です — オンデマンドの既定は毎秒 40,000 の読み込み/書き込みリクエストユニットです。Service Quotas で引き上げましょう。
DynamoDB TransactionConflictException — 原因と修正
TransactionConflictException は、別のトランザクションがすでに同じアイテムに触れていることを意味します。一時的です — バックオフで再試行し、トランザクションを小さく保ちましょう。
"Provisioned throughput decreases are limited within a given day" — 修正
DynamoDB は、UTC 日ごとにテーブルのプロビジョンドキャパシティを下げられる回数を制限します。クォータの計算と、UpdateTable エラーの回避方法を解説します。
DynamoDB On-Demand Throughput Exceeded — 原因と修正
オンデマンドのテーブルでもスロットリングは起きます — 設定した最大スループット、以前のピークの 2 倍を超える急増、またはテーブルのクォータが原因です。上限の引き上げ方を解説します。
DynamoDB Throttled Despite Capacity — Hot Partition の修正
各物理パーティションの上限が 3,000 RCU と 1,000 WCU のため、テーブルに余裕があっても DynamoDB は 1 つのホットパーティションキーをスロットリングします。その直し方を解説します。
DynamoDB TransactionInProgressException — 原因と修正
TransactWriteItems のリトライが、まだ実行中の試行と同じ ClientRequestToken を再利用しました。バックオフを入れて再試行し、タイムアウトを 5 秒より長く調整しましょう。
DynamoDB InternalServerError (HTTP 500) — 対処法
DynamoDB からの HTTP 500 は一時的なサービス側の障害で、再試行しても安全です — ただし失敗した書き込みが適用済みの可能性はあります。リトライの扱い方を解説します。
DynamoDB ReplicatedWriteConflictException — 原因と修正
マルチリージョンで強い整合性を持つグローバルテーブルでは、別のリージョンが同じアイテムを変更中だと書き込みが拒否されます。リトライ可能です — その扱い方を解説します。
テーブルとリソースのエラー (19)
DynamoDB ResourceNotFoundException — 原因と修正
ResourceNotFoundException は、指定したテーブルやインデックスが、呼び出しているリージョンとアカウントに存在しないことを意味します。名前、リージョン、認証情報を確認しましょう。
DynamoDB ResourceInUseException ("Table already exists") — 修正
ResourceInUseException は、テーブルがすでに存在するか、まだ CREATING・UPDATING・DELETING の途中であることを意味します。操作の前に DescribeTable でステータスを確認しましょう。
DynamoDB LimitExceededException — 原因と修正
LimitExceededException は、CreateTable・UpdateTable・DeleteTable の同時呼び出しが多すぎるか、アカウント制限に達したことを意味します。制限内に収める方法を解説します。
"The table does not have the specified index" — 修正
渡した IndexName がそのテーブルに存在しない、スペルミス、またはまだ GSI が ACTIVE でないため、DynamoDB が呼び出しを拒否しました。確認と修正の方法を解説します。
DynamoDB BackupNotFoundException — 原因と修正
DynamoDB BackupNotFoundException は、渡した BackupArn に一致するバックアップがないことを意味します。通常は誤った ARN、削除済みまたは期限切れのバックアップ、誤ったリージョンが原因です。
DynamoDB ReplicaNotFoundException — 原因と修正
ReplicaNotFoundException は、更新しようとしているリージョンレプリカがグローバルテーブルにないことを意味します — 誤ったリージョン、削除されたレプリカ、または競合が原因です。
"Attempting to modify a GSI that is being created" — 修正
DynamoDB は、グローバルセカンダリインデックスがまだ構築中の間、構造の変更をブロックします。IndexStatus が ACTIVE になるのを待つか、変更を順序立てて行いましょう。
DynamoDB ExportTableToPointInTime — PITR 無効エラーの修正
ExportTableToPointInTime はソーステーブルでポイントインタイムリカバリが有効である必要があり、無効だと PointInTimeRecoveryUnavailableException をスローします。コマンド 1 つの修正。
DynamoDB Global Table Version Mismatch — 原因と修正
グローバルテーブルの作成は、レプリカが揃わないときに失敗します — 空でないテーブル、一致しないキースキーマや GSI、2017 と 2019 の API バージョンの混在。
DynamoDB LSI Item Collection 10 GB Limit — 原因と修正
ローカルセカンダリインデックスを持つテーブルは各アイテムコレクションを 10 GB に制限します。超えると書き込みが失敗します。ItemCollectionMetrics を監視して再シャーディングしましょう。方法を解説します。
DynamoDB Cannot Access Stream — Stream Not Enabled の修正
コンシューマーが、DynamoDB Streams を無効にしたテーブルのストリームを読もうとしたか、古い ARN を使ったことが原因です。対象のテーブルで DynamoDB Streams を有効にしたうえで、現在の LatestStreamArn を指すように設定し直しましょう。
DynamoDB TableAlreadyExistsException / "Table already exists" — 修正
復元は TableAlreadyExistsException を、CreateTable と ImportTable は ResourceInUseException を返します。対象の名前がすでに使われているので、別の名前を選びましょう。
DynamoDB Streams ExpiredIteratorException — 原因と修正
DynamoDB Streams のシャードイテレーターは 15 分間有効です。それ以降に使うと GetRecords が ExpiredIteratorException をスローします。データを失わずに再開する方法を解説します。
DynamoDB Streams TrimmedDataAccessException — 原因と修正
ストリームレコードの保持は 24 時間なので、それより古いチェックポイントは TrimmedDataAccessException をスローします。TRIM_HORIZON から再開し、テーブルから突き合わせましょう。
DynamoDB BackupInUseException — 原因と修正
DynamoDB BackupInUseException は、同じテーブルに対する別のバックアップ操作がまだ実行中であることを意味します。完了を待ってから呼び出しを再試行してください。
DynamoDB InvalidRestoreTimeException — 原因と修正
InvalidRestoreTimeException は、RestoreDateTime が最大 35 日というテーブルの PITR ウィンドウの外にあることを意味します。読み方と有効な復元時刻の選び方を解説します。
DynamoDB PointInTimeRecoveryUnavailableException — 修正
PITR が有効になったことのないテーブルでポイントインタイム復元を試みました。今後のために継続バックアップを有効にし、今日必要なデータにはオンデマンドバックアップを使いましょう。
DynamoDB GlobalTableNotFoundException — 原因と修正
GlobalTableNotFoundException は、レガシーのグローバルテーブル API がテーブルを見つけられないことを意味します。通常は UpdateTable で管理する 2019.11.21 のグローバルテーブルが原因です。
DynamoDB ReplicaAlreadyExistsException — 原因と修正
すでにグローバルテーブルの一部であるレプリカリージョンを追加するよう DynamoDB に求めました。まずレプリケーショングループを記述し、レプリカ管理を冪等にしましょう。
認証と設定のエラー (13)
"not authorized to perform dynamodb:..." — AccessDeniedException の修正
DynamoDB の AccessDeniedException は、IAM アイデンティティにメッセージが示すアクションの実行権限がないことを意味します。読み方と IAM ポリシーの直し方を解説します。
"ConfigError: Missing region in config" — DynamoDB の修正
AWS SDK が、DynamoDB リクエストをどのリージョンに送るか判別できませんでした。クライアント、AWS_REGION、または AWS 設定で指定しましょう — 各選択肢を解説します。
"The security token included in the request is invalid" — DynamoDB の修正
この UnrecognizedClientException は、AWS の認証情報が誤っている、期限切れである、または読み込まれていないことを意味します。どれなのかを突き止めて直す方法を解説します。
DynamoDB IncompleteSignatureException — 原因と修正
IncompleteSignatureException は、SigV4 署名が不正な形式だったことを意味します — たいていは自前で組み立てた署名か、Authorization ヘッダーを書き換えたプロキシが原因です。
"The security token included in the request is expired" — DynamoDB の修正
ExpiredTokenException は、一時的な STS・SSO・引き受けたロールの認証情報がタイムアウトしたことを意味します。aws sso login を再実行し、古い AWS_SESSION_TOKEN をクリアしましょう。
"Unable to locate credentials" (boto3 / DynamoDB) — 修正
boto3 は、プロバイダーチェーンのどこからも AWS の認証情報が得られないとき NoCredentialsError を発生させます — 環境変数も、プロファイルも、インスタンスロールもない状態です。その直し方。
"The request signature we calculated does not match" — 修正
SigV4 の署名に失敗すると、DynamoDB は SignatureDoesNotMatch ではなく InvalidSignatureException を返します。たいていはシークレットキーの誤りか、マシンの時計のずれが原因です。
"Credential should be scoped to a valid region" — DynamoDB の修正
この SigV4 エラーは、認証情報スコープのリージョンが実際に呼び出したリージョンと一致しないことを意味します。クライアントとエンドポイントのリージョンを揃える方法を解説します。
"InvalidSignatureException: Signature expired" — DynamoDB の修正
DynamoDB は、署名のタイムスタンプが AWS のサーバー時刻から 5 分以上ずれたリクエストを拒否します。ほぼ必ずクライアントのクロックスキューが原因です — その直し方を解説します。
"Missing Authentication Token" — DynamoDB エラーの修正
DynamoDB の MissingAuthenticationTokenException は、誤ったエンドポイント URL やパス、あるいは署名されなかったリクエストを意味します。それぞれの直し方を解説します。
"Could not load credentials from any providers" (DynamoDB) — 修正
AWS SDK for JavaScript v3 は、認証情報チェーン全体が何も返さないとき CredentialsProviderError を発生させます。チェーンの解決順序と、それぞれの直し方を解説します。
"The SSO session associated with this profile has expired" — 修正
IAM Identity Center のトークンが失効すると、AWS CLI と SDK の DynamoDB 呼び出しが壊れます。aws sso login を実行し、それで足りなければ古い ~/.aws/sso/cache を消しましょう。
"The config profile could not be found" — AWS CLI と boto3 の修正
AWS CLI と boto3 は、指定したプロファイルが ~/.aws/config に存在しないとき ProfileNotFound を発生させます。よくある 3 つの原因と、それぞれの直し方。
DynamoDB Local とセットアップのエラー (8)
"Unable to start DynamoDB Local process" — 修正
DynamoDB Local の起動に失敗しました。通常は Java ランタイムの欠落/非互換、使用中のポート、または不正なインストールパスが原因です。それぞれの修正方法を解説します。
"Could not connect to DynamoDB Local" (ECONNREFUSED) — 修正
DynamoDB Local への ECONNREFUSED は、何も待ち受けていないことを意味します。通常はエミュレータの未起動、誤ったポート、または SDK が本物の AWS にアクセスしているのが原因です。
"Could not connect to the endpoint URL" (DynamoDB) — 修正
botocore は DynamoDB に到達できないとき EndpointConnectionError を発生させます。通常は誤ったエンドポイント URL、DynamoDB Local の未起動、誤ったリージョンが原因です。
DynamoDB Local "Address already in use" (ポート 8000) — 修正
DynamoDB Local は、何かがすでにポート 8000 を占有していると java.net.BindException をスローします。プロセスの特定、ポートの解放、別のポートでの起動方法を解説します。
DynamoDB Local "Failed to load native library sqlite4java" — 修正
DynamoDB Local は起動時に sqlite4java の UnsatisfiedLinkError で終了します。誤った java.library.path、または Apple Silicon のアーキテクチャ不一致が原因です。
"Unable to execute HTTP request" (DynamoDB, Java SDK) — 修正
AWS SDK for Java は、エンドポイントに到達できないとき Unable to execute HTTP request で失敗します。DynamoDB Local のダウン、誤ったポート、Docker のネットワークが原因です。
"Cannot do operations on a non-existent table" (DynamoDB Local) — 修正
DynamoDB Local は認証情報とリージョンの組み合わせごとに別々のデータベースを持つため、作成したテーブルが見えないことがあります。-sharedDb を付けて起動すれば 1 つを共有できます。
DynamoDB Local UnsupportedClassVersionError — 修正
DynamoDB Local 2.6.0 以降は Java 17 以降を必要とします。古い JRE では JVM がロードを拒否します。最新の JDK をインストールするか、Docker イメージを実行してください。
検証方法
ドキュメントは実装を言い換えたものであり、その言い換えは次第にずれていきます。これらのページで引用しているエラーメッセージは、すべて失敗する呼び出しを実際の AWS DynamoDB サービスに対して実行し、返ってきた内容を一字一句そのまま記録したものです — AWS のドキュメントから書き写したものではありません。
DynamoDB Local ではありません。エミュレータは手軽ですが、サービスと同じ文言でエラーを返すことを AWS は保証していません — 実際に確認したところ、メッセージの半数以上が異なっていました。その違いを知る価値がある場合は、ページに両方を掲載しています。
手を加えているのは、エラーそのものではなくリクエストを表す部分だけです。つまりテーブル名と、サービスがそのまま返してくるペイロードの写しです。サービスが一度も返したことのない文字列をページが引用していれば、テストがビルドを失敗させます — このテストがあるのは、私たち自身のページが、誰もコードを実行しないまま何か月も実在しないメッセージを引用していたからです。
14 種類の例外にわたる 58 件のメッセージ: 55 件は実サービスに対して取得したもの、2 件はリクエスト送信前に SDK が拒否したもの、1 件は DynamoDB Local 自身の文言そのものを扱ったものです。6 件には、同じ失敗をエミュレータがどう表現するかの注記が付いています。
- 実サービス
- Amazon DynamoDB (live service, us-east-1)
- エミュレータ（比較用）
- DynamoDB Local (amazon/dynamodb-local)
- JavaScript SDK
- @aws-sdk/client-dynamodb 3.1096.0
- Python SDK
- boto3 1.43.81 on Python 3.14.7
- Node.js
- v24.20.0