Repository navigation
[Kernel] Add specific exception subclasses for loadSnapshotAt version failures - #7055
Open
GabrielBBaldez wants to merge 3 commits into
Open
GabrielBBaldez wants to merge 3 commits into
GabrielBBaldez wants to merge 3 commits into
Conversation
1 of 5 tasks
seewishnew
added a commit
that referenced
this pull request
Oct 5, 2026
#### Which Delta project/connector is this regarding? - [ ] Spark - [ ] Standalone - [ ] Flink - [x] Kernel - [ ] Other (fill in here) ## Description `UCCatalogManagedClient` throws `IllegalArgumentException` when a requested snapshot version or commit-range boundary exceeds UC's latest ratified version. CDF streaming with `startingVersion=latest` requests `latest + 1`, so consumers need to distinguish an unavailable version from malformed arguments and other failures. Add `VersionToLoadAfterLatestCommitException` and use it for snapshot versions and explicit start/end versions above the catalog maximum, preserving the diagnostic messages. Invalid argument combinations, negative snapshot versions, and reversed ranges retain `IllegalArgumentException`. This supplies the precise UC failure type needed by #7754. Tests cover both the Kernel client and Spark snapshot-manager boundaries. This change shares the exception definition proposed in #7055, with contributor credit preserved, but does not include or depend on that PR's path-based or truncated-history changes. Either PR can merge first; the other can then reuse the shared class. Related to #6745. ## How was this patch tested? - Regression tests cover snapshot, range-start, and range-end versions at `latest + 1` and farther ahead, including exact exception type and diagnostic messages in the Kernel tests. The new future-version cases failed with the old `IllegalArgumentException` before their production changes. - All 52 tests passed across `UCCatalogManagedClientSuite`, `UCCatalogManagedClientCommitRangeSuite`, and `UcLoadSnapshotTelemetrySuite`. - All 10 `UCManagedTableSnapshotManagerSuite` tests passed on Spark 4.0, including propagation of the typed exception for future snapshot and range-boundary versions. - Earlier validation passed all 51 `SnapshotManagerSuite` tests without the path-based changes from #7055; that code is unchanged by the commit-range update. - Build-enforced Java/Scala formatting and Checkstyle, plus `git diff --check`, passed. Commands (Java 17): ```sh ./build/sbt 'kernelUnityCatalog/testOnly io.delta.kernel.unitycatalog.UCCatalogManagedClientSuite io.delta.kernel.unitycatalog.UCCatalogManagedClientCommitRangeSuite io.delta.kernel.unitycatalog.UcLoadSnapshotTelemetrySuite' ./build/sbt 'kernelApi/testOnly io.delta.kernel.internal.SnapshotManagerSuite' ./build/sbt -DsparkVersion=4.0 'sparkV2/testOnly io.delta.spark.internal.v2.snapshot.unitycatalog.UCManagedTableSnapshotManagerSuite' ``` ## Does this PR introduce _any_ user-facing changes? Yes. A UC snapshot request or explicit commit-range start/end version above the latest ratified version now throws `VersionToLoadAfterLatestCommitException` (a `KernelException`) instead of `IllegalArgumentException`. The messages are unchanged. Callers handling this condition should catch the specific type. --------- Signed-off-by: Vishnu Chandrashekhar <vishnu.c.9965@gmail.com> Co-authored-by: GabrielBBaldez <130607246+GabrielBBaldez@users.noreply.github.com>
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Which Delta project/connector is this regarding?
Description
When loading a snapshot at a specific version,
SnapshotManagercurrently signals both out-of-range failures with a genericKernelException, so callers can only tell them apart by string-matching the message.This adds two typed subclasses of
KernelExceptionand returns them from the correspondingDeltaErrorsfactory methods:VersionToLoadAfterLatestCommitException— the requested version is higher than the latest commit (not materialized yet; typically recoverable by retrying).VersionTruncatedException— the requested version is lower than the earliest available commit because the log has been truncated (unrecoverable for that version).Both extend
KernelException, mirroring howDeltaErrors#missingCheckpointalready returns anInvalidTableException. Connectors can nowcatchthe specific type instead of parsing the message — e.g. the delta-spark V2 CDCSparkMicroBatchStreamcan swallowVersionToLoadAfterLatestCommitExceptionto wait for the version to be committed.Resolves #6745.
How was this patch tested?
Updated the existing
SnapshotManagerSuitecases that exercise these two paths (getLogSegmentForVersion: versionToLoad higher than possibleand... not constructable from history) to assert the specific exception type is thrown instead of the genericRuntimeException.Does this PR introduce any user-facing changes?
No behavioral change: both new types extend
KernelException, so existingcatch (KernelException ...)keeps working and the messages are unchanged. Callers simply gain the option to catch the narrower types.