Skip to content

[FLINK-40476][docs] Clarify Changelog state backend requires CLAIM restore mode - #29025

Open
vsantwana wants to merge 1 commit into
apache:masterfrom
vsantwana:FLINK-40476-changelog-claim-docs
Open

[FLINK-40476][docs] Clarify Changelog state backend requires CLAIM restore mode#29025
vsantwana wants to merge 1 commit into
apache:masterfrom
vsantwana:FLINK-40476-changelog-claim-docs

Conversation

@vsantwana

Copy link
Copy Markdown
Contributor

What is the purpose of the change

Clarify the Changelog state backend documentation: NO_CLAIM restore mode (the default) is not supported. A changelog-enabled job resumed in NO_CLAIM mode restores successfully but then fails on its first checkpoint with:

java.lang.IllegalStateException: Configured state backend
(org.apache.flink.state.changelog.ChangelogStateBackend@...) does not support
enforcing a full snapshot. If you are restoring in NO_CLAIM mode, please consider
choosing CLAIM restore mode.

The docs previously stated "Resuming from both savepoints and checkpoints is supported" without noting the required restore mode, and the NO_CLAIM limitation was an easily-missed bullet that contradicted that statement. This mismatch contributed to FLINK-38307 being reported as a bug.

Brief change log

  • Note that resuming a job involving Changelog state must use CLAIM (or the deprecated LEGACY) restore mode, in both the "Enabling Changelog" and "Disabling Changelog" sections.
  • Add a warning note describing the exact failure that occurs in NO_CLAIM mode.
  • Expand the NO_CLAIM limitation bullet to point users to CLAIM/LEGACY.
  • Mirror all changes in the Chinese documentation (docs/content.zh).

Verifying this change

This change is a documentation-only change. The described behavior was verified empirically on Flink 1.19 (RocksDB + Changelog via the Kubernetes operator): resuming a changelog-enabled job in NO_CLAIM mode restores successfully but fails on the first checkpoint with the exception above, while the same job resumed in CLAIM mode resumes and checkpoints normally.

Does this pull request potentially affect one of the following parts:

  • Dependencies (does it add or upgrade a dependency): no
  • The public API, i.e., is any changed class annotated with @Public(Evolving): no
  • The serializers: no
  • The runtime per-record code paths (performance sensitive): no
  • Anything that affects deployment or recovery: no
  • The S3 file system connector: no

Documentation

  • Does this pull request introduce a new feature? no
  • If yes, how is the feature documented? docs (this PR updates documentation only)

…store mode

The Changelog state backend docs stated that resuming from savepoints and
checkpoints is supported, without noting that NO_CLAIM restore mode (the
default) is unsupported. A changelog-enabled job resumed in NO_CLAIM restores
successfully but then fails on its first checkpoint with
IllegalStateException: ... does not support enforcing a full snapshot.

Clarify that resuming a changelog job must use CLAIM (or the deprecated
LEGACY) restore mode, add a warning note describing the NO_CLAIM failure, and
expand the limitation bullet. Mirror the changes in the Chinese docs.
@flinkbot

flinkbot commented Aug 26, 2026

Copy link
Copy Markdown
Collaborator

CI report:

Bot commands The @flinkbot bot supports the following commands:
  • @flinkbot run azure re-run the last Azure build

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants