Claude Code “Sandbox Required but Unavailable”: What It Means

Claude Code “Sandbox Required but Unavailable”: What It Means

The Claude Code sandbox required but unavailable error means your settings demand a working sandbox, the sandbox can’t run, and Claude Code refuses to start without it. The setting behind it is usually sandbox.failIfUnavailable. Nothing is damaged, and your project files aren’t touched.

The text after the colon tells you what to fix. On Linux or WSL2, the usual cause is a missing package, so install bubblewrap and socat and restart. On native Windows or WSL1, Anthropic’s docs say the sandbox isn’t supported, so move to WSL2.

If the reason says the settings “failed validation,” the sandbox itself is fine. A value passed with --settings is wrong, such as "yes" where true belongs, and correcting that value is the whole fix.

Browse all our Claude Code tutorials for more fixes and how-tos.

Tested with Claude Code v2.1.330 on macOS on November 22, 2026. We reproduced the error with broken settings files in a throwaway demo project, then fixed them. The Linux, WSL2 and Windows steps follow Anthropic’s official instructions.

Quick Summary

Reason after the colonCauseFix
settings … failed validationWrong value or bad JSON in --settingsCorrect the key it names
dependencies are missingNo bubblewrap or socat (Linux, WSL2)Install both, restart
AppArmor restriction on user namespacesUbuntu blocks bubblewrapAdd the AppArmor profile, restart
WSL1 is not supportedOld WSL versionUpgrade to WSL2
not supportedNo sandbox for this platformUse WSL2 or a container

What “Sandbox Required but Unavailable” Means in Claude Code

The sandbox puts a wall around the shell commands Claude runs. It limits which files they can change and which sites they can reach. Our guide to the sandboxed Bash tool covers how it works day to day.

By default, a sandbox that can’t start doesn’t stop you. The docs say Claude Code runs commands without sandboxing instead. That’s risky for a team that counts on the wall being there.

So there is a stricter setting. With sandbox.failIfUnavailable set to true, Claude Code exits at startup when the sandbox can’t run. The changelog shows it arrived in v2.1.83.

Claude Code settings reference for sandbox.failIfUnavailable, saying Claude Code exits with an error at startup when the sandbox can't start
The settings reference: this key turns a sandbox problem into a startup error.
Diagram of the Claude Code startup check: if the sandbox can run the session starts, if failIfUnavailable is true it refuses, otherwise it starts with no sandbox
One setting decides between refusing to start and starting unprotected.

The error has two parts

The first line gives the reason, and the second points to the setting. The frame looks like this:

Error: sandbox required but unavailable: <reason>
  Refusing to start without a working sandbox (see sandbox.failIfUnavailable).

Read the reason before you touch the setting. The error is the safety feature doing its job.

We Reproduced the Error on v2.1.330

You can meet this error even on a Mac, where the sandbox is built in. We wrote a small settings file that gave allowedDomains a plain string instead of a list, and passed it with --settings:

Terminal showing Claude Code Error: sandbox required but unavailable, caused by sandbox.network.allowedDomains Expected array but received string, with exit code 1
The real error: one wrong value in bad-list.json, and Claude Code exits with code 1.

Look at that file again. It never sets failIfUnavailable, yet Claude Code still refused. When a --settings value turns the sandbox on but fails validation, startup stops, a change the changelog lists under v2.1.323.

A typo in the JSON does the same thing. Here the only mistake is a comma after the last value:

Terminal showing a settings file with a trailing comma and the Claude Code error sandbox required but unavailable, Invalid or malformed JSON
A trailing comma makes the JSON invalid, and the reason says so.

In an interactive session, the message can be hidden

Without -p, we got a Settings Error dialog first. It names the file, the key and the problem, which is all you need.

Claude Code Settings Error dialog naming bad-value.json and sandbox.failIfUnavailable, Expected boolean but received string, with three options
The dialog names the exact key. Option 2 is the one to pick here.

Choose “Exit and fix manually.” We also tried “Fix with Claude” and “Continue without these settings.” Both times the welcome screen flashed up and Claude Code closed with exit code 1, with no error text in our terminal.

Claude Code welcome screen followed by the shell prompt, where echo $? prints 1
If Claude Code opens and closes at once, check the exit code and run it again with -p.

So if your session vanishes right after it opens, add -p to the same command. That printed the full reason every time we tried it:

claude -p "hi" --settings ./your-settings.json

Every Reason, and What It Points To

We triggered the validation reason ourselves. The others below are message text we found inside the v2.1.330 program, matched with the docs page that explains the fix.

Reason textWhere you’d see it
sandbox is enabled but dependencies are missingLinux or WSL2, followed by names such as bubblewrap (bwrap) not installed or socat not installed
sandbox is enabled but cannot start hereThe packages are there, but something stops them
Ubuntu's AppArmor restriction on user namespaces stops bubblewrap hereUbuntu, as the detail in one of the reasons above
WSL1 is not supported (requires WSL2)Windows with WSL1
is not supported (requires macOS, Linux, or WSL2)Any other platform
failed validation, so none of them applyAny platform, from --settings or an SDK’s settings option

How to Fix “Sandbox Required but Unavailable”

Match your reason to a row, then jump to that fix.

Decision diagram matching the Claude Code sandbox error reason to its fix: failed validation, dependencies missing, AppArmor restriction, or unsupported platform
Find the words from your error on the left.

Fix 1: Install bubblewrap and socat (Linux and WSL2)

The sandbox needs different parts on each system, according to the sandboxing docs:

SystemWhat the sandbox needs
macOSNothing to install; it uses the built-in Seatbelt framework
Linuxbubblewrap and socat
WSL2bubblewrap and socat, installed inside WSL
WSL1Not supported
Native WindowsNot supported
Claude Code sandboxing docs showing the command sudo apt-get install bubblewrap socat for Ubuntu and Debian
The official install command for Ubuntu and Debian.

On Ubuntu or Debian, run:

sudo apt-get install bubblewrap socat

On Fedora, run:

sudo dnf install bubblewrap socat

Then start Claude Code again. The dependency check runs at startup, so a restart is needed. Ripgrep comes with the native program, and the seccomp filter is optional, so neither should block you there.

Fix 2: Lift Ubuntu’s AppArmor block

Some Ubuntu systems install both packages and still refuse. Their AppArmor rules stop bubblewrap from creating user namespaces, which it needs. Since v2.1.310, Claude Code names this cause in its message.

Claude Code docs on Ubuntu's AppArmor restriction, saying Claude Code refuses to start if sandbox.failIfUnavailable is true until the restriction is lifted
The docs: with failIfUnavailable on, the AppArmor block stops startup.

First, see which copy Claude Code will use:

which bwrap

If the answer is /usr/bin/bwrap, the docs give this AppArmor profile:

sudo tee /etc/apparmor.d/bwrap > /dev/null <<'EOF'
abi <abi/4.0>,
include <tunables/global>

profile bwrap /usr/bin/bwrap flags=(unconfined) {
  userns,
  include if exists <local/bwrap>
}
EOF

Reload AppArmor, then restart Claude Code:

sudo systemctl reload apparmor

For any other path, the docs offer sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0. It lifts the limit for every program until you reboot, so treat it as a short-term step.

Fix 3: Move to WSL2 on Windows

The docs are direct: the sandbox doesn’t run on native Windows, so with failIfUnavailable set, Claude Code exits at startup there.

Claude Code docs saying the sandbox doesn't run on native Windows, so with failIfUnavailable set Claude Code exits at startup on those machines
The docs suggest WSL2 or a container for Windows users.

If you already use WSL, check the version in PowerShell:

wsl -l -v

Version 1 has to be upgraded to 2. After that, install the two Linux packages from Fix 1 inside WSL and start Claude Code there.

Fix 4: Correct the settings value

When the reason says “failed validation,” the parentheses name the key. These are the mistakes we tested:

What we wroteMessageCorrect form
"failIfUnavailable": "yes"Expected boolean, but received string"failIfUnavailable": true
"allowedDomains": "github.com"Expected array, but received string"allowedDomains": ["github.com"]
true, before a closing braceInvalid or malformed JSONtrue with no comma

This is the version that worked:

{
  "sandbox": {
    "enabled": true,
    "failIfUnavailable": true,
    "network": { "allowedDomains": ["github.com"] }
  }
}
Terminal showing fixed.json with allowedDomains as a list, and claude -p replying ready with exit code 0
With the list in brackets, the same command starts and answers.

For a JSON typo, jq . your-settings.json points near the bad line. In our test, jq caught the trailing comma but passed the missing brackets, because that file is valid JSON with the wrong kind of value.

Fix 5: Change the requirement, if it’s yours to change

Maybe you don’t need a hard stop. Find where the key is set: .claude/settings.local.json, .claude/settings.json, ~/.claude/settings.json, a --settings value, or your organization’s managed settings. Our map of settings.json locations shows each path.

grep -n "failIfUnavailable" .claude/settings.local.json .claude/settings.json ~/.claude/settings.json

If the line is in your own file, you can set it to false. If it comes from managed settings, the docs say Claude Code uses the managed value and ignores yours, so ask your administrator. A failed load of those settings is a different error, covered in our managed settings guide.

Know the price before you switch it off. We set it to false and left the other mistake in place:

Claude Code warning Sandbox disabled, Commands will run WITHOUT sandboxing, Network and filesystem restrictions will NOT be enforced, then the reply ready
With failIfUnavailable set to false, Claude Code starts and only warns you.

Check That the Sandbox Really Works

Starting without an error is a good sign, but test it. The docs suggest asking Claude to create a file outside the project.

Don’t type the command at the ! prompt yourself, since that usually runs outside the sandbox.

Run touch ~/sandbox-probe with Bash, once. Don't retry. Quote the result in one line.
Claude Code Bash call touch ~/sandbox-probe failing with Operation not permitted because the sandbox only allows writes inside the project
We approved the command and the sandbox still blocked it. That’s the result you want.

On macOS the docs list Operation not permitted, which is what we got. On Linux and WSL2, expect Read-only file system. If the file is created, delete it and look at /sandbox.

Claude Code /sandbox panel on the Mode tab with Sandbox commands, with regular permissions checked
The /sandbox panel with the sandbox on. A panel with only a Dependencies tab means it can’t start.

Related Sandbox Messages

Two similar messages appear after Claude Code has started. The session stays open, but each sandboxed command is refused.

Claude Code docs section Commands are refused with Sandbox is required, explaining that the session keeps running while sandboxed commands are refused
The docs entry for the mid-session version of this problem.
MessageWhat the docs say to do
Sandbox is required but failed to initializeRestart, or fix the sandbox settings, as the message says
Sandbox is required ... and stopped being available in this sessionInstall what the reason names, then restart
Sandbox settings can't be changed hereA higher level sets them; check Setting sources in /status

We hit the last one with a healthy setup. Our sandbox keys came from --settings, which ranks above the file /sandbox writes to, so the panel stayed closed.

Claude Code /sandbox command answering Sandbox settings can't be changed here. Higher-priority settings override them.
Not a failure: the sandbox was on, and –settings controlled it.

Try It Yourself

You can see the error safely in an empty folder. This affects one launch and saves nothing to your settings:

claude -p "hi" --settings '{"sandbox":{"enabled":true,"failIfUnavailable":"yes"}}'

Read the reason, change "yes" to true, and run it again. On a Mac it should answer normally. On Linux, the result tells you whether your packages are in place.

Common Mistakes

  • Turning the requirement off before reading the reason. A one-word settings typo doesn’t need weaker security.
  • Installing the packages and not restarting. The check runs at startup.
  • Installing them in Windows instead of inside WSL2.
  • Putting quotes around true.
  • Expecting a broken project file to stop you. It may not, as the next test shows.

We put the same bad value in .claude/settings.json and ran claude -p. Claude Code skipped the whole file, printed a notice, and answered with exit code 0. The sandbox rules in that file weren’t in effect.

Claude Code reporting that the project .claude/settings.json did not load because failIfUnavailable expected boolean, then replying ready with exit code 0
A broken project settings file is skipped, so its sandbox requirement disappears with it.

Pro Tips

  • In CI, check the exit code. Every refusal in our claude -p runs returned 1 and gave no reply.
  • If a whole team needs the sandbox, use managed settings. The docs pair failIfUnavailable with "allowUnsandboxedCommands": false.
  • Mixed teams should deliver that rule only to macOS and Linux machines, since native Windows would exit at startup.
  • Run Claude Code as a normal user. Root brings its own startup error, which we explain in the root user fix.
  • Seeing something else? Our list of Claude Code errors covers the common ones, and claude doctor checks your setup.

Cheat Sheet

Cheat sheet for Claude Code sandbox required but unavailable: read the reason, Linux and WSL2 packages, settings values and who decides
Every check and fix from this guide on one card.

Frequently Asked Questions

What does “sandbox required but unavailable” mean in Claude Code?

Your settings say Claude Code must not run without a sandbox, and the sandbox can’t run. Claude Code stops at startup, and the text after the colon gives the reason.

How do I fix it on Ubuntu?

Install the packages with sudo apt-get install bubblewrap socat and restart Claude Code. If the message mentions AppArmor, add the profile from Fix 2 as well.

Why do I get it on a Mac?

The Mac sandbox needs no extra packages. In our tests the cause was a bad --settings value, so check the key in parentheses.

Is it safe to set failIfUnavailable to false?

It lets Claude Code start, but a sandbox that can’t run is then skipped and commands run without it. Do that only if you accept the risk and the rule is yours to change.

Does this stop Claude Code on the web?

It shouldn’t. The docs say a session in an Anthropic-hosted environment can start anyway, with a warning, and doesn’t enforce your sandbox.filesystem or sandbox.network rules.

Conclusion

The Claude Code sandbox required but unavailable error is a deliberate stop: something asked for a sandbox, and Claude Code won’t run commands without one. Read the reason first, then install bubblewrap and socat on Linux or WSL2, deal with AppArmor on Ubuntu, move off native Windows or WSL1, or correct the settings key it names. In our tests on v2.1.330, one wrong value in --settings was enough to trigger it, and one correction cleared it. To learn more about the model behind the tool, see our overview of Claude AI.

Newsletter

New AI tools in your inbox

The best new tools and the AI news that matters, in one short email. Unsubscribe any time.

Free · No spam · Unsubscribe any time

✓ Looks like you’re subscribed

Loading Google’s sign-up form…

Looks like you’re already subscribed

Thanks for reading! New AI tools and the AI news that matters will land in your inbox.

Not subscribed yet? Refresh the page to load the sign-up form.

The sign-up form couldn’t load. If you use an ad or content blocker, allow news.google.com and reload the page.

Free instant check before you pay. Takes a few seconds.

Scroll to Top