apache/iceberg · info

Unable to parse version from metadata location

Error message

Unable to parse version from metadata location: {}

What it means

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.

Solutions

1. Verify the metadata location string matches the standard pattern: version digits between the last '-' and '.metadata.json' / '.metadata' suffix.
2. Stop renaming or copying metadata files with custom names; let Iceberg write them.
3. If versions overflowed (extremely high commit counts), expire old snapshots and compact metadata to reset numbering, or migrate the table.
4. Check that the catalog writer version matches your Iceberg client version to avoid legacy naming.

Example fix

// before: hand-copying metadata under a new name
cp 00042-uuid.metadata.json custom-name.metadata.json
// after: reference the original metadata file location untouched
// metadata location stays: s3://bucket/db/tbl/metadata/00042-uuid.metadata.json

String name = Paths.get(location).getFileName().toString();
boolean standard = name.matches("\\d{5}-[0-9a-f-]+\\.metadata\\.json");

When it happens

Trigger: 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).

Common situations: 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.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• Cannot bind: does not accept arguments
• Cannot parse default as a
• Cannot parse
• Cannot parse to a duration string value
• Encountered invalid summary for snapshot

AI-assisted analysis of apache/iceberg@86d9c8fc54 (2026-09-12). Data as JSON: /api/errors/dc4bc9769e1c14f1. Report an issue: GitHub.

Appendix: source

Thrown at core/src/main/java/org/apache/iceberg/BaseMetastoreTableOperations.java:375

  /**
   * Parse the version from table metadata file name.
   *
   * @param metadataLocation table metadata file location
   * @return version of the table metadata file in success case and -1 if the version is not
   *     parsable (as a sign that the metadata is not part of this catalog)
   */
  private static int parseVersion(String metadataLocation) {
    int versionStart = metadataLocation.lastIndexOf('/') + 1; // if '/' isn't found, this will be 0
    int versionEnd = metadataLocation.indexOf('-', versionStart);
    if (versionEnd < 0) {
      // found filesystem table's metadata
      return -1;
    }

    try {
      return Integer.parseInt(metadataLocation.substring(versionStart, versionEnd));
    } catch (NumberFormatException e) {
      LOG.warn("Unable to parse version from metadata location: {}", metadataLocation, e);
      return -1;
    }
  }
}

View on GitHub (pinned to 86d9c8fc54)