[DOCS] Missing documentation for `sandbox.failIfUnavailable` setting

[coygeek]

Documentation Type

Missing documentation

Documentation Location

https://code.claude.com/docs/en/settings
https://code.claude.com/docs/en/sandboxing

---

Section/Topic

The sandbox settings reference table in the Settings page (under the sandbox configuration section) and the Sandboxing page's "Configure sandboxing" section. Neither page documents the sandbox.failIfUnavailable setting introduced in v2.1.83.

---

Current Documentation

The Settings page (/docs/en/settings) includes a sandbox configuration table with these keys:

Key	Description
enabled	Enable bash sandboxing. Default: false
autoAllowBashIfSandboxed	Auto-approve bash commands when sandboxed. Default: true
excludedCommands	Commands that should run outside of the sandbox
allowUnsandboxedCommands	Allow commands to run outside the sandbox via dangerouslyDisableSandbox. Default: true
filesystem.allowWrite	Additional paths where sandboxed commands can write
filesystem.denyWrite	Paths where sandboxed commands cannot write
filesystem.denyRead	Paths where sandboxed commands cannot read
filesystem.allowRead	Paths to re-allow reading within denyRead regions
filesystem.allowManagedReadPathsOnly	(Managed only) Restrict allowRead to managed settings only
network.allowUnixSockets	Unix socket paths accessible in sandbox
network.allowAllUnixSockets	Allow all Unix socket connections. Default: false
network.allowLocalBinding	Allow binding to localhost ports (macOS only). Default: false
network.allowedDomains	Domains to allow for outbound traffic
network.allowManagedDomainsOnly	(Managed only) Restrict allowed domains to managed settings only
network.httpProxyPort	HTTP proxy port for custom proxy
network.socksProxyPort	SOCKS5 proxy port for custom proxy
enableWeakerNestedSandbox	Weaker sandbox for unprivileged Docker environments
enableWeakerNetworkIsolation	Allow access to system TLS trust service (macOS only)

The Sandboxing page (/docs/en/sandboxing) describes the unsandboxed fallback behavior in a note:

Claude Code includes an intentional escape hatch mechanism that allows commands to run outside the sandbox when necessary. When a command fails due to sandbox restrictions... Claude is prompted to analyze the failure and may retry the command with the dangerouslyDisableSandbox parameter.

Neither page mentions sandbox.failIfUnavailable.

---

What's Wrong or Missing?

The sandbox.failIfUnavailable setting introduced in v2.1.83 is not documented anywhere. This setting controls what happens when sandboxing is enabled but the sandbox cannot start: with failIfUnavailable set to true, Claude Code exits with an error rather than silently falling back to running unsandboxed.

This is a security-relevant setting. Users and enterprise administrators who enable sandboxing to enforce isolation boundaries need to know that by default, a failed sandbox start causes Claude Code to run unsandboxed (the existing behavior), and that failIfUnavailable: true provides a strict-failure mode to prevent that silent downgrade. Without this documentation:

• Users cannot discover the setting exists
• Security-conscious operators have no way to enforce "sandbox or abort" policies
• The settings reference table is incomplete, making it inconsistent with the actual available configuration surface

---

Suggested Improvement

Add failIfUnavailable to the sandbox settings table in the Settings page:

Key	Description	Example
failIfUnavailable	When true, exit with an error if sandboxing is enabled but cannot start, instead of running unsandboxed. Useful for strict security policies where silent sandbox bypass is unacceptable. Default: false	true

On the Sandboxing page, in the "Configure sandboxing" section, add a note alongside the existing allowUnsandboxedCommands documentation:

To prevent Claude Code from running at all when the sandbox fails to start, set sandbox.failIfUnavailable to true. When enabled, Claude Code exits with an error if the sandbox cannot start, rather than falling back to unsandboxed execution. This complements allowUnsandboxedCommands: false, which prevents individual commands from escaping the sandbox, by also enforcing that the sandbox itself must be operational at startup.

Also update the configuration example JSON in the Settings page to illustrate the setting:

{
"sandbox": {
"enabled": true,
"failIfUnavailable": true
}
}

---

Impact

High

Additional Context

Affected Pages:

Page	URL	Issue
Settings	https://code.claude.com/docs/en/settings	sandbox.failIfUnavailable absent from sandbox settings table
Sandboxing	https://code.claude.com/docs/en/sandboxing	No mention of failIfUnavailable in configuration or security sections

Total scope: 2 pages

Source: Changelog v2.1.83

Exact changelog entry:

Added sandbox.failIfUnavailable setting to exit with an error when sandbox is enabled but cannot start, instead of running unsandboxed

[coygeek]

Issue #38557 Verification

Title: [DOCS] Missing documentation for sandbox.failIfUnavailable setting
Issue Date: 2026-03-25
Verification Date: 2026-03-27
Status: RESOLVED

---

Issue Summary

This issue reports that the sandbox.failIfUnavailable setting was missing from the Settings page sandbox configuration table and was not documented on the Sandboxing page's configuration guidance.

---

Verification Results

Claim 1: The Settings page omitted sandbox.failIfUnavailable from the sandbox settings table

Status: RESOLVED

At https://code.claude.com/docs/en/settings, line 272: "failIfUnavailable | Exit with an error at startup if sandbox.enabled is true but the sandbox cannot start (missing dependencies, unsupported platform, or platform restrictions). When false (default), a warning is shown and commands run unsandboxed. Intended for managed settings deployments that require sandboxing as a hard gate".

Verdict: The Settings page now includes the missing setting in the sandbox settings table and explains both the hard-failure behavior and the default unsandboxed fallback.

---

Claim 2: The Sandboxing page did not mention sandbox.failIfUnavailable or its startup-failure behavior

Status: RESOLVED

At https://code.claude.com/docs/en/sandboxing, line 100: "By default, if the sandbox cannot start (missing dependencies, unsupported platform, or platform restrictions), Claude Code shows a warning and runs commands without sandboxing. To make this a hard failure instead, set sandbox.failIfUnavailable to true. This is intended for managed deployments that require sandboxing as a security gate."

Verdict: The Sandboxing page now documents the setting directly and explains how it changes the startup behavior when sandboxing cannot be enabled.

---

Current State

Claim	Status
Settings page missing sandbox.failIfUnavailable in the sandbox settings table	RESOLVED
Sandboxing page missing sandbox.failIfUnavailable startup-failure guidance	RESOLVED

---

Suggested Fix

N/A - issue has been resolved.

---

References

• URL: https://code.claude.com/docs/en/settings
• Lines 265-275: Sandbox settings table includes the failIfUnavailable entry and describes its hard-failure behavior and default unsandboxed fallback.
• URL: https://code.claude.com/docs/en/sandboxing
• Lines 98-100: The configuration guidance explains the default unsandboxed fallback and says to set sandbox.failIfUnavailable to true for hard failure.

---

Conclusion & Recommendation

Primary Concern: The issue reported that the docs omitted sandbox.failIfUnavailable and did not explain how to prevent unsandboxed fallback when sandbox startup fails.

Resolution Status: RESOLVED

Recommendation: CLOSE

The missing setting is now documented on both cited pages. The current docs describe both the setting itself and the startup fallback behavior that the issue said was absent.

---

[github-actions]

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.