Skip to content

docs: Explain the cached data warning from the FDv2 file data source - #591

Merged
keelerm84 merged 1 commit into
mainfrom
mk/SDK-3619/file-source-cached-warning
Nov 20, 2026
Merged

keelerm84 merged 1 commit into
mainfrom
mk/SDK-3619/file-source-cached-warning

Conversation

@keelerm84

@keelerm84 keelerm84 commented Nov 20, 2026 •

Copy link
Copy Markdown
Member

Summary

A client whose only data source is the FDv2 file data source logs this warning once, on its first flag evaluation:

Feature Flag evaluation attempted before client has initialized - using last known values from feature store

The evaluation still uses the file data. The warning appears because file data has no LaunchDarkly selector, so the data system reports it as cached data, not as data refreshed from LaunchDarkly.

This PR changes no behavior. It documents the warning on Files.new_data_source_v2 and file_ds_builder, and pins the current behavior with tests: the FDv1 file source does not log the warning, and the FDv2 file source logs it exactly once, as an initializer, as a synchronizer, or as both, while it still returns the file values.

Whether the warning should go away is an open question. A comment below raises it for discussion.


Note

Overview
Documents that the FDv2 file data source has no LaunchDarkly selector, so the data system treats it as cached data rather than a refresh from LaunchDarkly. When file data is the only source, the first flag evaluation still uses the file values but logs a one-time warning: "Feature Flag evaluation attempted before client has initialized - using last known values from feature store".

Adds this explanation to Files.new_data_source_v2 and file_ds_builder, with a cross-reference between them. No runtime behavior changes.

New pinned tests assert FDv1 file sources do not emit that warning, while FDv2 logs it exactly once whether the builder is used as an initializer, synchronizer, or both—and evaluations still return the correct file-backed values.

Reviewed by Cursor Bugbot for commit eb3cb8e. Bugbot is set up for automated code reviews on this repo. Configure here.

@keelerm84

Copy link
Copy Markdown
Member Author

For discussion: should a full payload from a local source count as REFRESHED?

This PR documents the warning but leaves the behavior alone. I'd like reviewer input on whether we should change it.

Why it happens. data_availability returns REFRESHED only when the store's selector is defined (fdv2_common.py:279). The file source finishes its change set with Selector.no_selector() (file_data_sourcev2.py:226), so a file-only client stays CACHED, and the client logs the cached-data warning once (client.py:516).

Options I see:

  1. Leave it. The warning is accurate in a narrow sense: the data did not come from LaunchDarkly. The docs added here explain it.
  2. Count a full transfer from a local source as REFRESHED. The data system would treat a complete payload as current data even without a selector. This is the behavior change I would lean toward, but it touches the readiness rules, so it needs agreement.
  3. Give file data a synthetic selector. I don't think this is safe. If a polling synchronizer is also configured, it sends the store's selector to LaunchDarkly as its basis, so a made-up selector would reach the service.

Related. ld-relay#979 serves FDv2 polls when the store has data but no selector, and #582 changes readiness for selectorless initializers. If Relay sends selectorless payloads, clients behind Relay may end up in the same CACHED state. I have not confirmed that.

TestData is not affected: it builds a real selector (test_data_sourcev2.py:76).

@keelerm84
keelerm84 requested a review from a team as a code owner November 20, 2026 16:54

@cursor cursor Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Risk: low.

Automated risk review (dry run): Low

This PR would be automatically approved.

Why: The diff only documents the existing FDv2 file-source cached-data warning on Files.new_data_source_v2 and file_ds_builder, and pins that warning with tests in test_file_data_sources_pinned_behavior.py without changing runtime behavior.

If you disagree with this review, share this PR in #feedback-agent-approvals or submit a changes-requested review explaining why.

Open in Web View Automation 

Sent by Cursor Approval Agent: Dry-Run PR Approver

@cursor cursor Bot added the risk:low label Nov 20, 2026
@keelerm84
keelerm84 merged commit 5cc96b0 into main Nov 20, 2026
19 checks passed
@keelerm84
keelerm84 deleted the mk/SDK-3619/file-source-cached-warning branch November 20, 2026 18:34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants