{"record":{"id":"0ec35d2e9ea12683","repo":"apache/iceberg","slug":"metadata-file-for-version-d-is-missing-under-s","errorCode":null,"errorMessage":"Metadata file for version %d is missing under %s","messagePattern":"Metadata file for version (.+?) is missing under (.+?)","errorType":"exception","errorClass":"ValidationException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/apache/iceberg/hadoop/HadoopTableOperations.java","lineNumber":110,"sourceCode":"  private synchronized void updateVersionAndMetadata(int newVersion, String metadataFile) {\n    // update if the current version is out of date\n    if (version == null || version != newVersion) {\n      this.version = newVersion;\n      this.currentMetadata =\n          checkUUID(currentMetadata, TableMetadataParser.read(io(), metadataFile));\n    }\n  }\n\n  @Override\n  public TableMetadata refresh() {\n    int ver = version != null ? version : findVersion();\n    try {\n      Path metadataFile = getMetadataFile(ver);\n      if (version == null && metadataFile == null && ver == 0) {\n        // no v0 metadata means the table doesn't exist yet\n        return null;\n      } else if (metadataFile == null) {\n        throw new ValidationException(\n            \"Metadata file for version %d is missing under %s\", ver, metadataRoot());\n      }\n\n      Path nextMetadataFile = getMetadataFile(ver + 1);\n      while (nextMetadataFile != null) {\n        ver += 1;\n        metadataFile = nextMetadataFile;\n        nextMetadataFile = getMetadataFile(ver + 1);\n      }\n\n      updateVersionAndMetadata(ver, metadataFile.toString());\n\n      this.shouldRefresh = false;\n      return currentMetadata;\n    } catch (IOException e) {\n      throw new RuntimeIOException(e, \"Failed to refresh the table\");\n    }\n  }","sourceCodeStart":92,"sourceCodeEnd":128,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/core/src/main/java/org/apache/iceberg/hadoop/HadoopTableOperations.java#L92-L128","documentation":"HadoopTableOperations.refresh() resolves the current table version by looking for version-hint/metadata files under the metadata root. If no metadata file exists for the expected version (and it is not the legitimate v0 case), the library cannot determine table state and throws ValidationException. This guards against a corrupt or truncated metadata directory.","triggerScenarios":"Calling Table.refresh() / current() when version-hint.text points at version N but vN.metadata.json is absent under the metadata root; concurrent writers or manual deletion of metadata files; the temporary-operations path resolving a version that was never committed.","commonSituations":"Manually deleting or moving metadata JSON files; a failed/incomplete commit left version-hint.text ahead of actual files; writing the table to HDFS and then copying only data files; race between two writers where one renames files away.","solutions":["Verify version-hint.text matches an existing v<N>.metadata.json.gz/json file in the metadata directory and correct the hint file if stale","Restore the missing metadata file from backup or object-store versioning","List the metadata directory for the highest valid version file and rewrite version-hint.text to that version","Rebuild the table by re-importing data if metadata is unrecoverable"],"exampleFix":"// before: hint file says version 5 but only v4 exists\n// after: fix hint file to the highest existing version\necho 4 > /warehouse/db/table/metadata/version-hint.text","handlingStrategy":"validation","validationCode":"Path meta = new Path(root, \"metadata\");\nif (!fs.exists(new Path(meta, \"version-hint.text\")) ||\n    !fs.globStatus(new Path(meta, \"v*.metadata.json*\"), p -> true).isEmpty()) {\n  // proceed only when hint and metadata files agree\n}","typeGuard":null,"tryCatchPattern":"try { table.refresh(); } catch (ValidationException e) { /* inspect metadata dir, repair version-hint.text */ }","preventionTips":["Never delete or move files under the metadata directory manually","After copy/restore operations, validate version-hint.text matches an existing vN metadata file","Use object-store versioning or backups for the metadata directory","Monitor for writers killed mid-commit"],"tags":["hadoop","metadata","validation"],"backgroundTag":"file-not-found","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"}