{"record":{"id":"f72ea196699e98e0","repo":"apache/iceberg","slug":"received-unexpected-failure-when-committing-to","errorCode":null,"errorMessage":"Received unexpected failure when committing to {}, validating if commit ended up succeeding.","messagePattern":"Received unexpected failure when committing to (.+?), validating if commit ended up succeeding\\.","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"aws/src/main/java/org/apache/iceberg/aws/dynamodb/DynamoDbTableOperations.java","lineNumber":132,"sourceCode":"              GetItemRequest.builder()\n                  .tableName(awsProperties.dynamoDbTableName())\n                  .consistentRead(true)\n                  .key(tableKey)\n                  .build());\n      checkMetadataLocation(table, base);\n      Map<String, String> properties = prepareProperties(table, newMetadataLocation);\n      persistTable(tableKey, table, properties, retryDetector);\n      commitStatus = CommitStatus.SUCCESS;\n    } catch (CommitFailedException e) {\n      // any explicit commit failures are passed up and out to the retry handler\n      throw e;\n    } catch (RuntimeException persistFailure) {\n      boolean conditionCheckFailed = persistFailure instanceof ConditionalCheckFailedException;\n\n      // If we got an exception we weren't expecting, or we got a ConditionalCheckFailedException\n      // but retries were performed, attempt to reconcile the actual commit status.\n      if (!conditionCheckFailed || retryDetector.retried()) {\n        LOG.warn(\n            \"Received unexpected failure when committing to {}, validating if commit ended up succeeding.\",\n            fullTableName,\n            persistFailure);\n        commitStatus = checkCommitStatus(newMetadataLocation, metadata);\n      }\n\n      if (commitStatus != CommitStatus.SUCCESS && conditionCheckFailed) {\n        throw new CommitFailedException(\n            persistFailure, \"Cannot commit %s: concurrent update detected\", tableName());\n      }\n\n      switch (commitStatus) {\n        case SUCCESS:\n          break;\n        case FAILURE:\n          throw new CommitFailedException(\n              persistFailure, \"Cannot commit %s due to unexpected exception\", tableName());\n        case UNKNOWN:","sourceCodeStart":114,"sourceCodeEnd":150,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/aws/src/main/java/org/apache/iceberg/aws/dynamodb/DynamoDbTableOperations.java#L114-L150","documentation":"A warning from DynamoDbTableOperations.doCommit: the persist call to DynamoDB failed, and since the failure was either unexpected (not a ConditionalCheckFailedException) or a conditional-check failure after retries were performed, the commit outcome is ambiguous. The code calls checkCommitStatus to read back the table entry and determine whether the commit actually succeeded before deciding what exception to throw.","triggerScenarios":"Any RuntimeException from the DynamoDB persist (network error, throttling, provisioned throughput exceeded, service outage), or a ConditionalCheckFailedException raised after the retry detector observed retries — meaning the commit may or may not have landed.","commonSituations":"DynamoDB throttling under load; transient network partitions between the job and DynamoDB; long-running commits where another writer already updated the record so retries exhaust; IAM permission issues causing unexpected errors.","solutions":["Inspect the logged persistFailure cause (throttling, access denied, etc.) and address the underlying DynamoDB issue","Enable retries/backoff and adequate table capacity to reduce transient failures","If commit-status reconciliation reports the commit succeeded, no action is needed; if it reports failure, retry the write idempotently","Check IAM policies allow the conditional PutItem/UpdateItem on the catalog table"],"exampleFix":"// no caller code change — fix the environment\n// before: table with 1 RCU getting throttled\n// after: switch to on-demand billing or raise capacity\ndynamodb.updateTable(t -> t.tableName(tableName)\n    .provisionedThroughput(p -> p.readCapacityUnits(50L).writeCapacityUnits(50L)));","handlingStrategy":"retry","validationCode":"// pre-check IAM/capacity\n// ensure the principal can conditionally write the catalog item\n// and that table capacity/on-demand is enabled","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Configure SDK retry strategy with exponential backoff","Use on-demand DynamoDB billing for bursty commit traffic","Avoid many concurrent committers to the same table","On CommitStateUnknownException, verify the table's metadata location before re-committing"],"tags":["aws","dynamodb","commit","optimistic-concurrency"],"backgroundTag":"http-error-response","analyzedSha":"86d9c8fc543e7c56c9f624eb725f76c9baff9570","analyzedAt":"2026-09-12T00:46:39.097Z","contentChangedAt":"2026-09-12T00:46:39.097Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}