[DOCS] [Server-managed settings] Document partial-apply behavior when a delivered payload contains an invalid entry

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/server-managed-settings

Section/Topic

## Settings delivery -> ### Fetch and caching behavior (and any related "what happens on a bad payload" callout). The page also lacks a general "Payload validation" or "Invalid entries" subsection under ## Settings delivery that describes the new partial-apply contract.

Current Documentation

The page currently documents fetch success, failure, and caching behavior, but does not describe what happens when the delivered payload itself is malformed in part. Relevant quoted excerpts:

First launch without cached settings: Claude Code fetches settings asynchronously If the fetch fails, Claude Code continues without managed settings * There is a brief window before settings load where restrictions are not yet enforced

Subsequent launches with cached settings: Cached settings apply immediately at startup Claude Code fetches fresh settings in the background * Cached settings persist through network failures

The ### Enforce fail-closed startup subsection documents forceRemoteSettingsRefresh: true, and ### Security approval dialogs documents the user-facing approval flow for risky settings. There is no subsection that documents what Claude Code does when the payload is delivered successfully but contains an entry that fails validation.

What's Wrong or Missing?

A. Missing documentation of partial-apply contract for invalid entries

As of v2.1.169, when a server-delivered settings payload contains one or more invalid entries, Claude Code now applies the remaining valid policies instead of silently dropping the entire payload, and the validation error is surfaced. The server-managed-settings page does not describe this contract anywhere, so administrators cannot tell from the docs:

1. Whether a single bad entry will break the rest of the managed tier (it will not, in v2.1.169+).
2. Where the validation error surfaces (it is reported to the user, not silently swallowed).
3. How to diagnose the problem when a managed policy appears to be missing in production.

This is the same conceptual gap the changelog entry addresses, but the docs have not been updated to reflect it. A reader of the page cannot determine the current behavior from the documented text.

B. Related but distinct behavior change not yet linked

The v2.1.166 changelog also notes that "Errors from invalid managed settings are now surfaced." Neither that change nor the v2.1.169 follow-up is mentioned in the page. Cross-linking these two behaviors would help administrators reason about "the policy is missing" vs. "the policy is being applied but the user is being told something is wrong" troubleshooting paths.

Suggested Improvement

Add a new subsection under ## Settings delivery (between ### Enforce fail-closed startup and ### Security approval dialogs) that describes the new partial-apply contract. Suggested wording:

### Invalid entries in a delivered payload If the server returns a payload that contains one or more invalid entries (for example, a malformed allowedMcpServers predicate or a value that fails schema validation), Claude Code applies the remaining valid policies from that payload rather than discarding the whole tier. The validation error is surfaced to the user so it can be diagnosed. This behavior applies to both server-managed and file-based managed settings payloads. To see which entry was rejected, run /status and inspect the reported issue, or run claude doctor for a warning that names the offending entry. The unchanged entries continue to take effect on the same startup that reports the error.

Add a one-line note in the v2.1.169 entry of any "What's new" or version-history block on the page, and cross-reference the existing ### Enforce fail-closed startup section so readers understand that the fail-closed setting is unrelated to the new partial-apply behavior on a successful fetch.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/server-managed-settings | Primary documentation location; "Settings delivery" section has no "invalid entries" subsection |
| https://code.claude.com/docs/en/settings | Settings reference; the "Configuration scopes" and "Setting sources" sections already note /status reports invalid JSON, but they do not mention partial-apply for invalid entries in a delivered payload |

Related changelog entries (Claude Code, v2.1.169):

• "Remote-managed settings with an invalid entry now apply their remaining valid policies and surface the validation error, instead of silently dropping the whole payload"
• (v2.1.166) "Errors from invalid managed settings are now surfaced"

Related changelog entry (v2.1.166): "Fixed managed settings with an invalid entry silently disabling enforcement of their remaining valid policies" describes the same symptom from the file-based managed-settings path. The two entries together justify a single docs paragraph that covers both the server-managed and file-based tiers.

Why the v2.1.168 entry is related but distinct: the v2.1.168 fix is for the endpoint-managed / file-based managed-settings payload, and the v2.1.169 fix is for the server-delivered payload. Both should be covered in the same docs paragraph, since administrators often maintain both tiers.