An organisation-wide policy that silently fails to load is worse than no policy at all: it looks like protection while providing none. Claude Code reports on this directly, through two separate diagnostic lines that cover two separate delivery paths, and knowing which one you're looking at matters for interpreting what it says.
The two ways a policy reaches a machine
Claude Code supports two approaches to centralised configuration, and each has its own diagnostic. Server-managed settings are configured by an Owner in Admin Settings > Claude Code > Managed settings in the claude.ai console, and Claude Code fetches them over the network at startup and polls for updates hourly during a session. Endpoint-managed settings are deployed directly to a device instead: a managed-settings.json file at a fixed system path (/etc/claude-code/managed-settings.json on Linux, for example), a macOS managed preference, or a Windows registry policy, placed there by MDM or another fleet-management tool.
Both occupy the highest tier in Claude Code's settings hierarchy, overriding anything a developer sets themselves. But they're delivered differently, fail differently, and Claude Code reports on each with a different line.
Managed settings (remote): the server-managed settings check
This line requires Claude Code v2.1.248 or later. Run claude doctor and look for Managed settings (remote), which reports one of four outcomes:
- The delivered settings loaded
- Your organisation has no server-managed settings configured
- The fetch failed, with the cause and whether a cached policy still applies
- Claude Code skipped the fetch, with the reason
While the fetch is still in progress, the line reports that instead of one of the four outcomes above. In a running session, /status shows the same line after a failed fetch, and for some skipped-fetch causes too, such as a third-party provider variable or a custom ANTHROPIC_BASE_URL set in the user's own shell, either of which routes the session away from Anthropic's API entirely and makes a server-managed settings fetch meaningless.
This diagnostic is specific to server-managed settings. It doesn't tell you whether an endpoint-managed file also exists or applied, only what happened when Claude Code tried to reach the console-configured policy.
Organization policy: the broader, newer check
Added in v2.1.261, released 4 September 2026, this line covers the outcome that actually matters day to day: whichever managed source won, and whether it loaded. Per the managed settings documentation: "To check whether these organization settings reached a given machine, run claude doctor there and read the Organization policy line, which says where Claude Code loaded the policy from or why it didn't load." The v2.1.261 changelog's own example of a failure reason is a proxy not passing the settings endpoint through, the kind of network-layer problem that's easy to miss until a machine that should be locked down turns out not to be.
In a running session, /status shows the same line specifically when the policy didn't load, mirroring how the remote-settings line behaves. Both diagnostics require running claude doctor on the actual machine in question. Neither one is visible from the admin console; the console shows what you configured, not what reached any particular device.
How settings actually get chosen when more than one source exists
Within the managed tier, Claude Code checks server-managed settings first, then endpoint-managed settings, applying the first source that delivers at least one policy key, apart from a small set of exception keys. Two of those exceptions are worth knowing before you go looking for a mismatch:
- Cross-source lock keys, such as the sandbox allowlist locks, are honoured when any admin-controlled managed source sets them, not just the one Claude Code selected as primary.
- The
envblock merges per key across the admin-controlled sources in v2.1.223 and later, rather than only the selected source's whole block applying. The highest-priority source that defines a given environment variable wins that variable specifically, and a lower-priority source fills in anything the higher one leaves unset.
If you've cleared a server-managed configuration expecting Claude Code to fall back cleanly to an endpoint-managed file, remember that cached server settings can persist on client machines until the next successful fetch, and that some keys, model among them, only take effect at the next launch regardless of source. /status shows which managed source is actually active on a given machine, which is the fastest way to settle a question like this rather than reasoning about precedence rules in the abstract.
Why a fetch actually fails, and what happens next
Claude Code doesn't fail loudly by default when a settings fetch doesn't come back. On a first launch with no cached settings, Claude Code waits up to five seconds for the policy before opening the session; if the payload needs a security approval dialog, the wait ends early and the payload applies once the user approves it. On any other launch, or once that five-second window runs out, Claude Code opens the session while the fetch keeps running in the background, so a short window can pass before restrictions actually take effect. If the fetch fails outright, Claude Code proceeds without server-managed settings and, in an interactive session, warns that no remote policy applies; endpoint-managed settings, if any exist on that device, still apply regardless.
On a subsequent launch, cached settings apply immediately, with one deliberate exception: Claude Code withholds several categories of cached environment variables, proxy and TLS configuration, API routing and provider-selection variables, authentication credentials, and the configuration-directory selector, until the current session's fetch actually confirms the payload. This closes an otherwise real gap: a cached proxy or credential value could redirect or intercept the very fetch meant to confirm or replace it. A cached modelPricing value behaves the same way, staying unapplied until confirmed, so cost figures in /usage and the status line show list price in the interim rather than a stale contracted rate.
For environments where even that brief window is unacceptable, forceRemoteSettingsRefresh: true in your managed settings blocks startup until a fresh fetch succeeds, exiting instead of proceeding on a cached or absent policy if it fails:
{
"forceRemoteSettingsRefresh": true
}
This is self-perpetuating once delivered: it's cached locally too, so later startups keep enforcing it even before that session's own fetch succeeds. Before turning it on, confirm your network actually reaches api.anthropic.com reliably. If it doesn't, this setting is what stops Claude Code from starting at all rather than merely warning.
Security approval dialogs can hold up a rollout
Some settings need a user's explicit approval before Claude Code applies them in an interactive session, precisely because they carry real risk if silently accepted: settings that execute shell commands (apiKeyHelper, statusLine), settings pointing at sandbox binaries, settings that let the sandbox proxy read or reroute traffic, custom environment variables such as proxy or base-URL values, and any hook configuration at all. If a user rejects the dialog, Claude Code exits rather than continuing with a partial or unapproved policy.
This matters for diagnosing a rollout that seems stuck: a policy that looks like it should be live but isn't yet visible on a user's machine may simply be waiting on that user to see and approve the dialog, rather than having failed to fetch at all. Approval is remembered per organisation for a claude.ai login, per gateway for a Claude apps gateway sign-in, and per credential otherwise, and Claude Code shows the dialog again whenever the approval-requiring settings actually change, not on every login.
Debugging a specific machine
When a diagnostic line alone doesn't explain enough, run:
claude --debug-file /tmp/claude-debug.log
and search the resulting log for Remote settings. This is the same debug path Anthropic's own documentation points to for delivery issues, and it's worth reaching for before assuming a payload problem is a Claude Code bug rather than something specific to that machine's network path or credentials.
Before rolling a managed settings change out organisation-wide, validate it on one test machine first: save the change, then run claude doctor there and confirm the Organization policy and Managed settings (remote) lines show what you expect. If part of a payload fails schema validation, Claude Code salvages and applies every remaining valid setting rather than rejecting the whole payload, in v2.1.169 and later; only a payload where nothing at all can be salvaged is rejected outright, in which case Claude Code keeps the last-accepted cached settings and logs Remote settings: Settings validation failed - no fields could be salvaged.
A worked example
Say your organisation just added a permission deny rule through server-managed settings to block reading .env files across every developer's machine, and you want to confirm it actually reached someone's laptop before trusting it. On that machine:
claude doctor
Read the Managed settings (remote) line first: it should say the delivered settings loaded. Then check Organization policy, which confirms the policy as a whole, this source or any endpoint-managed source that might also apply, loaded successfully. If either line reports a failure, the reason it gives, a network problem, a proxy issue, a skipped fetch, tells you exactly where to look next rather than leaving you to guess between a client bug and a genuinely undelivered policy.
Troubleshooting
Organization policy reports a proxy not passing the endpoint through. Confirm your organisation's proxy explicitly allows traffic to api.anthropic.com rather than blocking it by default or stripping the request en route. This is the exact failure mode named in the v2.1.261 changelog.
Managed settings (remote) says the fetch was skipped, not failed. A skip usually means the session's authentication method doesn't fetch server-managed settings on this platform, or a shell-set ANTHROPIC_BASE_URL or third-party provider variable is already routing the session elsewhere. Check platform availability for which setups skip the fetch by design.
A policy change isn't visible on a user's machine yet. Check whether a security approval dialog is waiting for that user to accept it before it applies; some changes need explicit per-user approval rather than applying silently.
I cleared server-managed settings but an endpoint-managed file isn't taking over. Cached server settings can persist on a client until its next successful fetch. Run /status to see which managed source is currently active, rather than assuming the fallback happened instantly.
A policyHelper script isn't being consulted. Claude Code ignores a policyHelper configured in MDM or a file-based source whenever server-managed settings are delivering a policy key; the helper only takes over as the sole managed configuration when it's the source Claude Code actually selected.
Where this fits
For the full delivery mechanics behind both diagnostics, see Claude Code's own managed settings and server-managed settings documentation. For a related managed setting that provisions MCP servers the same way, see managedMcpServers explained. For configuring auto mode's classifier through the same managed settings pipeline, see auto mode's trusted infrastructure. Browse Claude Code's settings and install paths at getclaudeskills.com/platforms/claude-code.
Verified 6 September 2026 directly against code.claude.com's managed-settings and server-managed-settings documentation, both read in full, and the v2.1.261 changelog entry dated 4 September 2026.
