{"record":{"id":"cd66f991edd6b048","repo":"apache/iceberg","slug":"failed-to-write-manifest","errorCode":null,"errorMessage":"Failed to write manifest","messagePattern":"Failed to write manifest","errorType":"exception","errorClass":"RuntimeIOException","httpStatus":null,"severity":"critical","filePath":"core/src/main/java/org/apache/iceberg/FastAppend.java","lineNumber":156,"sourceCode":"        manifest.partitionSpecId(),\n        toCopy,\n        current.specsById(),\n        newManifestFile,\n        snapshotId(),\n        summaryBuilder);\n  }\n\n  @Override\n  public List<ManifestFile> apply(TableMetadata base, Snapshot snapshot) {\n    List<ManifestFile> manifests = Lists.newArrayList();\n\n    try {\n      List<ManifestFile> newWrittenManifests = writeNewManifests();\n      if (newWrittenManifests != null) {\n        manifests.addAll(newWrittenManifests);\n      }\n    } catch (IOException e) {\n      throw new RuntimeIOException(e, \"Failed to write manifest\");\n    }\n\n    Iterable<ManifestFile> appendManifestsWithMetadata =\n        Iterables.transform(\n            Iterables.concat(appendManifests, rewrittenAppendManifests),\n            manifest -> GenericManifestFile.copyOf(manifest).withSnapshotId(snapshotId()).build());\n    Iterables.addAll(manifests, appendManifestsWithMetadata);\n\n    if (snapshot != null) {\n      manifests.addAll(snapshot.allManifests(ops().io()));\n    }\n\n    summaryBuilder.merge(buildManifestCountSummary(manifests, 0));\n\n    return manifests;\n  }\n\n  @Override","sourceCodeStart":138,"sourceCodeEnd":174,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/core/src/main/java/org/apache/iceberg/FastAppend.java#L138-L174","documentation":"FastAppend.apply wraps its call to writeNewManifests() in a try/catch that converts any IOException from the underlying manifest writer into RuntimeIOException('Failed to write manifest'). It means Iceberg could not write a new Avro manifest file to the table's FileIO while preparing an append snapshot, so the append cannot be committed.","triggerScenarios":"Calling table.newFastAppend().appendFile(...).apply() (or commit) when the manifest writer fails: unwritable target location, expired/invalid cloud credentials, missing bucket, HDFS NameNode unreachable, disk full, or FileIO misconfiguration.","commonSituations":"S3/GCS credentials rotated or missing IAM permissions on the table location; HDFS in safe mode; network partition to storage; wrong warehouse path configured (read-only or nonexistent filesystem); local FS used in container with read-only rootfs.","solutions":["Check the wrapped cause (`e.getCause()` / RuntimeIOException.getCause()) for the real storage error and fix storage access (credentials, permissions, connectivity).","Verify the table location and write.target-file-size / write locations are writable by the job's identity.","Test FileIO directly: write a scratch file to the same location with the same FileIO config before retrying the append.","Retry the append after transient network/storage failures; FastAppend.apply() has no side effects on commit failure."],"exampleFix":"// before: swallowing the cause\ncatch (IOException e) {\n  throw new RuntimeIOException(e, \"Failed to write manifest\");\n}\n// after (user side): surface the root cause\ntry {\n  append.commit();\n} catch (RuntimeIOException e) {\n  LOG.error(\"Manifest write failed; root cause: {}\", e.getCause(), e);\n  throw e;\n}","handlingStrategy":"retry","validationCode":"// pre-flight: ensure the table location is writable with the current FileIO\nfileIO.newOutputFile(tableLocation + \"/.write-check\").create();","typeGuard":null,"tryCatchPattern":"try {\n  table.newFastAppend().appendFile(df).commit();\n} catch (RuntimeIOException e) {\n  LOG.error(\"Manifest write failed; root cause\", e.getCause());\n  if (isTransient(e.getCause())) retryWithBackoff();\n  else throw e;\n}","preventionTips":["Verify storage credentials/IAM permissions for the table location before write jobs.","Monitor disk space and HDFS health (safe mode, NameNode availability).","Use the same FileIO configuration in a smoke test as in production writes.","Retry transient storage errors with backoff; apply()/commit() is safe to re-run."],"tags":["io","manifest","file-write-failed","storage"],"backgroundTag":"file-write-failed","analyzedSha":"86d9c8fc543e7c56c9f624eb725f76c9baff9570","analyzedAt":"2026-09-12T00:46:39.097Z","contentChangedAt":"2026-09-12T00:46:39.097Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}