{"record":{"id":"c01040969d352e4d","repo":"apache/iceberg","slug":"unknown-time-travel-timetravel","errorCode":null,"errorMessage":"Unknown time travel: \" + timeTravel","messagePattern":"Unknown time travel: \" \\+ timeTravel","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"spark/v4.1/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.1/spark/src/main/java/org/apache/iceberg/spark/source/SparkTable.java#L314-L350","documentation":"SparkTable.create resolves time travel specifications from Spark's TIME TRAVEL spec; it supports no time travel, AsOfVersion, and AsOfTimestamp. Any other TimeTravel spec instance is rejected with IllegalArgumentException, meaning Spark produced a time travel expression Iceberg does not recognize.","triggerScenarios":"CREATE TABLE ... AS / DataFrame read with VERSION AS OF or TIMESTAMP AS OF that resolves to an unexpected TimeTravel subtype passed to SparkTable.create(table, timeTravel).","commonSituations":"Spark version mismatches where new time travel specs exist; custom catalog/planner wrappers producing a non-standard TimeTravel implementation; using snapshot-id-based travel through an unsupported syntax variant.","solutions":["Use the supported syntax: `VERSION AS OF` / `TIMESTAMP AS OF` (or `FOR VERSION AS OF` / `FOR TIMESTAMP AS OF`).","Check Spark and Iceberg versions are compatible (spark/v4.1 module expects Spark 4.1).","Pass a plain table or an AsOfVersion/AsOfTimestamp when calling SparkTable.create programmatically.","Upgrade Iceberg if the Spark version introduced new TimeTravel variants."],"exampleFix":"// before\nspark.read.option(\"as-of\", something).table(\"db.tbl\")\n// after\nspark.read.table(\"db.tbl\").option(\"version-as-of\", \"1234567890\")  // or\nspark.sql(\"SELECT * FROM db.tbl VERSION AS OF 1234567890\")","handlingStrategy":"validation","validationCode":"if (timeTravel != null && !(timeTravel instanceof AsOfVersion) && !(timeTravel instanceof AsOfTimestamp)) { throw new IllegalArgumentException(\"unsupported time travel: \" + timeTravel); }","typeGuard":"boolean supported = timeTravel == null || timeTravel instanceof AsOfVersion || timeTravel instanceof AsOfTimestamp;","tryCatchPattern":"try { return SparkTable.create(table, timeTravel); } catch (IllegalArgumentException e) { throw new AnalysisException(\"Use VERSION AS OF or TIMESTAMP AS OF\", e); }","preventionTips":["Use standard VERSION AS OF / TIMESTAMP AS OF syntax","Pin compatible Spark and Iceberg versions","Avoid wrapping TimeTravel specs in custom subclasses"],"tags":["invalid-argument","time-travel","spark"],"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-23T08:17:48.524Z"}