Fix: Claude Code 2m Bash Timeout

Written by Michael Lip · Solo founder of Zovo · $400K+ on Upwork · 100% JSS Join 50+ builders · More at zovo.one

The Error

A long-running bash command in Claude Code gets killed after approximately 2 minutes. This commonly hits during npm install, docker build, cargo build, test suites, database migrations, and deployment scripts.

Quick Fix

Ask Claude to run the command in the background:

Run `npm install` in the background so it doesn't time out

Claude Code will run the command as a background task and check results when it completes.

What Causes This

Claude Code’s Bash tool has a default timeout of 120,000 milliseconds (2 minutes) for command execution, controlled by the BASH_DEFAULT_TIMEOUT_MS environment variable. The maximum timeout the model can set is 600,000 milliseconds (10 minutes), controlled by BASH_MAX_TIMEOUT_MS.

The timeout exists to prevent hung commands from blocking the session indefinitely. However, many legitimate development commands regularly exceed 2 minutes:

Command Typical Duration
npm install (large project) 2-5 minutes
docker build (multi-stage) 3-15 minutes
cargo build (Rust, release) 5-30 minutes
Full test suite 2-60 minutes
Database migration 1-10 minutes

Full Solution

Option 1: Use Background Execution

Tell Claude to run long commands in the background:

Run this command in the background: npm ci && npm run build && npm test

Claude Code will start the command as a background process, return immediately, and check the task’s output when it completes.

Option 2: Increase the Default Timeout

Set the BASH_DEFAULT_TIMEOUT_MS environment variable before launching Claude Code:

# Set default to 10 minutes (600000ms)
export BASH_DEFAULT_TIMEOUT_MS=600000
claude

Or add it to your shell profile for persistence:

echo 'export BASH_DEFAULT_TIMEOUT_MS=600000' >> ~/.bashrc
source ~/.bashrc

You can also increase the maximum timeout the model can request:

# Set max to 10 minutes (the default maximum)
export BASH_MAX_TIMEOUT_MS=600000

Option 3: Break Commands Into Stages

Instead of one long command, break it into steps that each complete within the timeout window:

Instead of: "Run npm ci && npm run build && npm test"

Do:
1. "Run npm ci"
2. (wait for completion)
3. "Run npm run build"
4. (wait for completion)
5. "Run npm test"

Each step runs independently with its own timeout window.

Option 4: Pre-Run Long Commands Yourself

For commands you know will take a while, run them in a separate terminal:

# In a separate terminal (not Claude Code)
npm ci && echo "DONE: npm ci"

# Then tell Claude Code
# "npm ci is complete. The node_modules are installed. Continue with the build."

Prevention