How do I turn off structured outputs in Claude Code with `CLAUDE_CODE_DISABLE_STRUCTURED_OUTPUTS`?

On Claude Code 2.1.288 or later, set CLAUDE_CODE_DISABLE_STRUCTURED_OUTPUTS to 1 when a gateway rejects output_config.format. 0 does not disable it.

On Claude Code v2.1.288 or later, set CLAUDE_CODE_DISABLE_STRUCTURED_OUTPUTS=1. Claude Code then stops sending the structured-output output_config.format field and the anthropic-beta value that pairs with it. The variable exists for LLM gateways, and Mantle per the changelog, whose upstream rejects those fields, which broke session titles, memory recall, and prompt hooks. Use 1. Setting it to 0 keeps structured outputs on. It's an env var only, with no slash command or settings key. It's not the Claude API structured outputs feature.

TL;DR: Variable CLAUDE_CODE_DISABLE_STRUCTURED_OUTPUTS · value 1 · floor v2.1.288 · removes only output_config.format + its beta header · narrower than CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS. Checked 2026-10-05.

What the variable does

The Claude Code CHANGELOG entry for 2.1.288 reads:

Fixed session titles, memory recall and prompt hooks failing on Mantle or behind gateways that reject structured outputs; added CLAUDE_CODE_DISABLE_STRUCTURED_OUTPUTS to turn structured outputs off

The environment variables page adds the precise scope. Set it to 1 "to stop Claude Code from sending the structured-output output_config.format field and the anthropic-beta value that pairs with it, for an LLM gateway whose upstream rejects them." It "leaves on the other pre-release capabilities that CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS turns off."

Symptom to recognize. The LLM gateway protocol page describes it as a 400 naming output_config, often with Extra inputs are not permitted, on Amazon Bedrock and Google Cloud's Agent Platform upstreams. If your gateway forwards Anthropic-format requests to one of those, this is the fix to try first.

The docs don't say what Claude Code does internally for titles or memory once the format field is gone, so we won't guess.

How to set it

Shell, before launching:

export CLAUDE_CODE_DISABLE_STRUCTURED_OUTPUTS=1
claude

Settings file, using the generic env key:

{
  "env": {
    "CLAUDE_CODE_DISABLE_STRUCTURED_OUTPUTS": "1"
  }
}

Put it in ~/.claude/settings.json (just you), .claude/settings.json (whole project, checked in), .claude/settings.local.json (you, this project), or managed settings to enforce it org-wide. See managed settings. For the broader env and provider setup, see Claude Code API keys and env.

Docs say a running session picks up changed env values when you save the settings file, except features that read their variables once at startup. They don't say which group this variable falls in [GAP], so relaunch claude after the change to be safe. Shell exports always need a relaunch.

Value rules. Most on/off variables in Claude Code treat 1/true/yes/on as on and 0/false/no/off as off. This variable isn't on the docs' short list of "any non-empty value counts" exceptions, so 0 does not disable structured outputs. Its own row says 1, so use 1.

Check your version with claude --version. Below 2.1.288 the variable does nothing.

This var vs `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS`

Both switches remove the format field. The older one removes a lot more. Per the gateway protocol docs (checked 2026-10-05):

Removes	`CLAUDE_CODE_DISABLE_STRUCTURED_OUTPUTS=1`	`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`
`output_config.format` + its beta	Yes	Yes (v2.1.287+)
`output_config.task_budget`	No	Yes
`context_management` field	No	Yes
Beta tool fields (`strict`, `defer_loading`)	No	Yes
MCP tool search	No	Yes (tools load upfront unless managed settings keep it on)
`output_config.effort`	No	No
Minimum version	2.1.288	format removal from 2.1.287

Rule: if only output_config format errors are failing, use the narrow switch and keep the other capabilities. Better still, per the docs' first option, have the gateway forward the field and its headers together. Reach for CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS when several pre-release fields are being rejected.

Same pattern as the sibling Spec on turning off WebFetch: one documented env var, value 1, no slash command.

If you searched for Claude API structured outputs

You probably want something else. The Claude API's structured outputs feature is where your app sends a JSON schema to the Messages API and gets schema-conforming output back. That's covered in Anthropic's structured outputs docs. This variable doesn't turn that on or off for your own API calls.

Claude Code's --json-schema flag in -p mode is also a separate feature. The env-vars row for this variable doesn't mention it, and we haven't tested any interaction [GAP].

Pitfalls

Setting 0 and expecting "off." 0 means the disable switch is off, so structured outputs stay on.
Running an older build. Below 2.1.288 the variable is ignored.
Over-disabling. CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS also drops task budget, context management, beta tool fields, and MCP tool search.
Hunting for a toggle. No /config entry, slash command, or dedicated settings key exists in the docs we checked. Use the env key.
Not relaunching after editing settings (advice, see the [GAP] above).

FAQ

What value do I set?

1.

Which version do I need?

Claude Code v2.1.288 or later.

Does it turn off effort?

No. It removes only the format field. Effort stays even with CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS, and the docs describe a separate automatic retry when an upstream rejects output_config.effort.

Is this the Claude API structured outputs feature?

No. See the API docs.

Sources (checked 2026-10-05)

Claude Code CHANGELOG, entries 2.1.288 and 2.1.287 (latest entry at fetch: 2.1.289)
Environment variables
LLM gateway protocol, feature pass-through and "Disable pre-release capabilities"
Claude API structured outputs (fence only)