{"record":{"id":"55481d6d21fa4177","repo":"apache/iceberg","slug":"unknown-time-travel-timetravel-55481d","errorCode":null,"errorMessage":"Unknown time travel: ${timeTravel}","messagePattern":"Unknown time travel: (.+?)","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"spark/v4.2/spark/src/main/java/org/apache/iceberg/spark/source/SparkTable.java","lineNumber":332,"sourceCode":"  }\n\n  public static SparkTable create(Table table, String branch) {\n    ValidationException.check(\n        branch == null || SnapshotRef.MAIN_BRANCH.equals(branch) || table.snapshot(branch) != null,\n        \"Cannot use branch (does not exist): %s\",\n        branch);\n    return new SparkTable(table, branch);\n  }\n\n  public static SparkTable create(Table table, TimeTravel timeTravel) {\n    if (timeTravel == null) {\n      return new SparkTable(table);\n    } else if (timeTravel instanceof AsOfVersion asOfVersion) {\n      return createWithVersion(table, asOfVersion);\n    } else if (timeTravel instanceof AsOfTimestamp asOfTimestamp) {\n      return createWithTimestamp(table, asOfTimestamp);\n    } else {\n      throw new IllegalArgumentException(\"Unknown time travel: \" + timeTravel);\n    }\n  }\n\n  private static SparkTable createWithVersion(Table table, AsOfVersion timeTravel) {\n    if (timeTravel.isSnapshotId()) {\n      return new SparkTable(table, Long.parseLong(timeTravel.version()), timeTravel);\n    } else {\n      SnapshotRef ref = table.refs().get(timeTravel.version());\n      Preconditions.checkArgument(\n          ref != null,\n          \"Cannot find matching snapshot ID or reference name for version %s\",\n          timeTravel.version());\n      if (ref.isBranch()) {\n        return new SparkTable(table, timeTravel.version());\n      } else {\n        return new SparkTable(table, ref.snapshotId(), timeTravel);\n      }\n    }","sourceCodeStart":314,"sourceCodeEnd":350,"githubUrl":"https://github.com/apache/iceberg/blob/86d9c8fc543e7c56c9f624eb725f76c9baff9570/spark/v4.2/spark/src/main/java/org/apache/iceberg/spark/source/SparkTable.java#L314-L350","documentation":"SparkTable.create() maps Spark's timeTravel spec to an Iceberg snapshot: AsOfVersion maps to version/snapshot-id travel, AsOfTimestamp to timestamp travel. Any other TimeTravel subclass triggers IllegalArgumentException('Unknown time travel: ...') because Iceberg cannot interpret it.","triggerScenarios":"Executing a time travel query where Spark passes a TimeTravel implementation other than AsOfVersion or AsOfTimestamp — usually a newer Spark feature or custom catalog extension's spec.","commonSituations":"Spark/Iceberg version skew where a new time-travel variant was added in Spark but the bundled Iceberg connector doesn't recognize it; custom CatalogPlugin supplying its own TimeTravel implementation.","solutions":["Upgrade the Iceberg Spark connector to match your Spark version so all TimeTravel variants are handled","Use standard VERSION AS OF or TIMESTAMP AS OF syntax, which map to AsOfVersion/AsOfTimestamp","Avoid custom time-travel specs with the Iceberg catalog","Check spark-sql syntax; e.g. use 'SELECT * FROM t VERSION AS OF 123' rather than proprietary variants"],"exampleFix":"// before\nSELECT * FROM tbl FOR VERSION AS OF 'abc'; -- nonstandard spec\n// after\nSELECT * FROM tbl VERSION AS OF 4695933054711295165; -- AsOfVersion, supported","handlingStrategy":"validation","validationCode":"boolean supported = timeTravel instanceof AsOfVersion || timeTravel instanceof AsOfTimestamp; if (!supported) throw new IllegalArgumentException(\"Time travel spec not supported by Iceberg: \" + timeTravel);","typeGuard":"boolean isSupportedTimeTravel(TimeTravel t) { return t instanceof AsOfVersion || t instanceof AsOfTimestamp; }","tryCatchPattern":"try { return SparkTable.create(table, timeTravel); } catch (IllegalArgumentException e) { log.error(\"Unsupported time travel spec\", e); throw e; }","preventionTips":["Use VERSION AS OF / TIMESTAMP AS OF syntax only","Keep the Iceberg connector version matched to Spark","Avoid custom TimeTravel implementations with the Iceberg catalog"],"tags":["spark","iceberg","time-travel","illegal-argument"],"backgroundTag":"invalid-enum-value","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"}