[gustavohstrassburger]

💡 Motivation and Context

Why: sdk-specs #85 defines how a server SDK reports flags that local evaluation could not resolve. Today such a flag is absent from the evaluateFlags() snapshot, so it looks the same as a flag that does not exist, and $feature_flag_called reports flag_missing for both. With onlyEvaluateLocally this is permanent. posthog-node already implements this (PostHog/posthog-js#5234).

This replaces #827, which was closed as stale. It is rebased on main and adds the spec parts that #827 did not have.

Changes in posthog-server:

• PostHogFeatureFlagEvaluations.unresolvedFlags maps each unresolved flag to a PostHogUnresolvedFlagReason (EXPERIENCE_CONTINUITY, UNSUPPORTED_DEFINITION, UNRESOLVED_DEPENDENCY, MISSING_CONTEXT). When several causes apply, the spec's fixed precedence picks one. Snapshots from only() / onlyAccessed() have no entries, and reading the map is not an access.
• A snapshot read of an unresolved flag reports local_evaluation_inconclusive instead of flag_missing. Values, keys and capture enrichment do not change.
• Every inconclusive raise site carries a reason, including the newer regex and numeric sites. A bad person value is MISSING_CONTEXT; a bad filter value is UNSUPPORTED_DEFINITION.
• Behavior change: a condition no longer stops at the first inconclusive filter. If another filter does not match, the condition resolves locally as no match instead of falling back to /flags.
• When definitions load, the SDK logs one warning (also with debug off) for each flag local evaluation can never resolve. It repeats only when that flag's definition changes; 304 and unchanged cache loads do not repeat it.

Divergences from the spec or posthog-node:

• A missing group key still resolves to false, as before, so it is not reported as MISSING_CONTEXT. posthog-node does the same.
• The SDK has no device-id bucketing, so the device-id acceptance row does not apply.
• A static cohort is an ordinary inconclusive filter (UNSUPPORTED_DEFINITION). posthog-node also forces a server fallback when the static cohort is the first filter it cannot check; this SDK has no separate "requires server" signal, so it keeps its current behavior.
• An unexpected error inside a dependency stays flag_missing instead of UNRESOLVED_DEPENDENCY.

💚 How did you test it?

Unit tests mirror every scenario tagged @unresolved_flags_capable and @unresolvable_flag_warning_capable in acceptance/public/evaluate-flags.feature, plus precedence, the condition loop and the load-time checks. Run locally with JDK 17:

• ./gradlew :posthog-server:test (656 tests, 0 failures)
• make checkFormat
• ./gradlew :posthog-server:apiCheck
• ./gradlew :posthog-server-openfeature:test

No manual testing in an app.

📝 Checklist

• All commits are signed (see Commit signing)
• I reviewed the submitted code.
• I added tests to verify the changes.
• I updated the docs if needed.
• No breaking change or entry added to the changelog.

If releasing new changes

• Ran pnpm changeset to generate a changeset file

🤖 Agent context

Autonomy: Human-driven (agent-assisted)

• Written with Claude Code in PostHog Desktop, from a cross-SDK plan to apply sdk-specs chore: improve API error message #85 to all server SDKs.
• Started from the feat(server): expose flags that local evaluation could not resolve #827 commit, resolved its conflicts with fix(server): log when local-only evaluation omits continuity flags #824 (the unresolved list now feeds the local-only experience continuity log), then added the spec's reason precedence, the condition loop change, dependency reasons, the UNSUPPORTED_DEFINITION warning and warning-level logging.

---

Created with PostHog Desktop

🤖 Generated with Claude Code

[posthog]

PostHog Review · Standard · reviewed d8d13e9: 3 Should fix. This pull request is large, so the review ran in 4 parts with less depth than usual.

This is the only automatic review while this pull request is a draft. Comment @posthog review to review new changes sooner. Otherwise, a review of the new changes runs when you mark it ready for review.

See this review and its findings in PostHog Review. Comment @posthog review --deep for a Deep review. A Deep review takes longer and looks deeper than a Standard review.

[posthog]

PostHog Review · Standard · reviewed 987b468: no findings. This pull request is large, so the review ran in 4 parts with less depth than usual.