{"record":{"id":"a085da0b12949188","repo":"apache/iceberg","slug":"cannot-commit-s-due-to-unexpected-exception","errorCode":null,"errorMessage":"Cannot commit %s due to unexpected exception","messagePattern":"Cannot commit (.+?) due to unexpected exception","errorType":"exception","errorClass":"CommitFailedException","httpStatus":409,"severity":"error","filePath":"aws/src/main/java/org/apache/iceberg/aws/dynamodb/DynamoDbTableOperations.java","lineNumber":148,"sourceCode":"      // 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:\n          throw new CommitStateUnknownException(persistFailure);\n      }\n    } finally {\n      try {\n        if (commitStatus == CommitStatus.FAILURE) {\n          // if anything went wrong, clean up the uncommitted metadata file\n          io().deleteFile(newMetadataLocation);\n        }\n      } catch (RuntimeException e) {\n        LOG.error(\"Failed to cleanup metadata file at {}\", newMetadataLocation, e);\n      }\n    }\n  }\n\n  private void checkMetadataLocation(GetItemResponse table, TableMetadata base) {\n    String dynamoMetadataLocation = table.hasItem() ? getMetadataLocation(table) : null;","sourceCodeStart":130,"sourceCodeEnd":166,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/aws/src/main/java/org/apache/iceberg/aws/dynamodb/DynamoDbTableOperations.java#L130-L166","documentation":"CommitFailedException (with persistFailure as cause) thrown in doCommit when checkCommitStatus returns CommitStatus.FAILURE, meaning the persist step failed with an unexpected exception and the commit definitely did not succeed. The original failure is chained.","triggerScenarios":"The conditional Dynamo update (or the metadata file write) threw persistFailure, and the subsequent commit-status check determined the commit definitively failed.","commonSituations":"DynamoDB throughput exceeded or throttling during putItem; transient network failure writing the metadata JSON file; IAM permission missing for the metadata location.","solutions":["Inspect the chained cause (persistFailure) — fix the underlying persist error first","Retry the commit after refreshing the table","Check DynamoDB capacity/provisioned throughput and IAM write permissions on the warehouse location"],"exampleFix":"// before\n// cause hidden in logs\n// after\ntry {\n  table.append(df);\n} catch (CommitFailedException e) {\n  LOG.error(\"persist failure cause\", e.getCause()); // inspect real failure\n  throw e;\n}","handlingStrategy":"retry","validationCode":"// pre-check permissions and throughput\n dynamo.describeTable(b -> b.tableName(catalogTable)); // accessible?\n // verify warehouse location is writable via FileIO","typeGuard":null,"tryCatchPattern":"try {\n  table.append(df);\n} catch (CommitFailedException e) {\n  Throwable cause = e.getCause(); // real persist failure\n  LOG.error(\"Persist failed\", cause);\n  if (isTransient(cause)) {\n    table.refresh();\n    table.append(df);\n  } else {\n    throw e;\n  }\n}","preventionTips":["Always inspect getCause() — this message wraps the real failure","Set adequate DynamoDB throughput/on-demand billing","Grant write access to both the Dynamo catalog table and the metadata warehouse"],"tags":["aws","dynamodb","commit-failure"],"backgroundTag":"database-write-failed","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"}