{"record":{"id":"dc4bc9769e1c14f1","repo":"apache/iceberg","slug":"unable-to-parse-version-from-metadata-location","errorCode":null,"errorMessage":"Unable to parse version from metadata location: {}","messagePattern":"Unable to parse version from metadata location: (.+?)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"info","filePath":"core/src/main/java/org/apache/iceberg/BaseMetastoreTableOperations.java","lineNumber":375,"sourceCode":"  /**\n   * Parse the version from table metadata file name.\n   *\n   * @param metadataLocation table metadata file location\n   * @return version of the table metadata file in success case and -1 if the version is not\n   *     parsable (as a sign that the metadata is not part of this catalog)\n   */\n  private static int parseVersion(String metadataLocation) {\n    int versionStart = metadataLocation.lastIndexOf('/') + 1; // if '/' isn't found, this will be 0\n    int versionEnd = metadataLocation.indexOf('-', versionStart);\n    if (versionEnd < 0) {\n      // found filesystem table's metadata\n      return -1;\n    }\n\n    try {\n      return Integer.parseInt(metadataLocation.substring(versionStart, versionEnd));\n    } catch (NumberFormatException e) {\n      LOG.warn(\"Unable to parse version from metadata location: {}\", metadataLocation, e);\n      return -1;\n    }\n  }\n}\n","sourceCodeStart":357,"sourceCodeEnd":380,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/core/src/main/java/org/apache/iceberg/BaseMetastoreTableOperations.java#L357-L380","documentation":"A WARN log from parseVersion when the numeric version segment of a metadata JSON file location (e.g. .../metadata/00003-abc.metadata.json) cannot be parsed as an integer. The method returns -1, which callers interpret as 'version unknown'; it can disable optimizations that rely on version ordering and signals a malformed or non-standard metadata file name. It is tolerated, not fatal.","triggerScenarios":"refreshFromMetadataLocation is given a metadata location whose file name does not contain a parseable integer version between the last '-' and the '.' before 'metadata' (custom naming schemes, hand-copied metadata files, version overflow beyond Integer.MAX_VALUE).","commonSituations":"Custom FileIO or catalog implementations writing metadata with non-Iceberg naming; files renamed or symlinked by tooling; very old metadata written by a buggy writer; Integer overflow with metadata version > 2^31-1 after millions of commits.","solutions":["Verify the metadata location string matches the standard pattern: version digits between the last '-' and '.metadata.json' / '.metadata' suffix.","Stop renaming or copying metadata files with custom names; let Iceberg write them.","If versions overflowed (extremely high commit counts), expire old snapshots and compact metadata to reset numbering, or migrate the table.","Check that the catalog writer version matches your Iceberg client version to avoid legacy naming."],"exampleFix":"// before: hand-copying metadata under a new name\ncp 00042-uuid.metadata.json custom-name.metadata.json\n// after: reference the original metadata file location untouched\n// metadata location stays: s3://bucket/db/tbl/metadata/00042-uuid.metadata.json","handlingStrategy":"validation","validationCode":"String name = Paths.get(location).getFileName().toString();\nboolean standard = name.matches(\"\\\\d{5}-[0-9a-f-]+\\\\.metadata\\\\.json\");","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Never rename or hand-edit Iceberg metadata files","Use standard Iceberg writers for all commits","Keep Iceberg client and catalog writer versions aligned","Monitor for -1 version returns if you rely on version-based cleanup"],"tags":["metadata-location","parsing","version"],"backgroundTag":"invalid-argument-format","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"}