Skip to content
BabelBabel Docs

Troubleshooting

Start with diagnostics

Section titled “Start with diagnostics”
Terminal window
node .\babel-cli\dist\index.js doctor
node .\babel-cli\dist\index.js setup --json

doctor reports environment findings without a provider key. setup --json gives a machine-readable view. Both may legitimately report missing prerequisites — read the findings rather than expecting a green checklist.

Common causes

Section titled “Common causes”

“Node version not supported”

Section titled ““Node version not supported””

The CLI targets Node.js 22.19.0+ in the 22.x line or 24.13.1+ in the 24.x line. Check node --version and babel-cli/package.json engines.

Model session fails to start

Section titled “Model session fails to start”
  • No provider credential: use Desktop Providers and models, the private CLI profile (~/.babel/config/.env), or your shell environment. Shell/CI variables take precedence. The old checkout-local babel-cli/.env is loaded only with explicit BABEL_LEGACY_CLI_ENV=1 compatibility opt-in.
  • Wrong provider for the route: choose the provider whose credential you configured, enable a qualified model, and save it as the default. A saved key’s presence does not prove authentication. Verify source CLI setup with node .\babel-cli\dist\index.js models ping --json (requires a configured provider).
  • Read the actual provider error: invalid credentials, insufficient balance, inaccessible models and provider outages require different fixes. Desktop retains the error instead of substituting another provider. Plan and Deep currently require OpenRouter; select Chat for other Desktop providers.

Execution blocked / “fail-closed” without Docker

Section titled “Execution blocked / “fail-closed” without Docker”

This is expected behavior, not a bug to route around. The default safe_repo profile requires Docker isolation and a configured sandbox image (BABEL_BENCHMARK_DOCKER_IMAGE). Without them, shell execution fails closed.

In Desktop Setup, start Docker Desktop with Linux containers, then choose Prepare recommended image or validate an existing local image. Recheck setup after repairing Docker or restoring a removed image. Desktop and its installed CLI launcher share the verified image setting. Custom images must include the tools your project tests need; the recommended image provides Git, Node and npm.

Your options, in order of preference:

  1. Install/start Docker and configure the sandbox image, keep safe_repo.
  2. Keep safe_repo but explicitly allow host execution with BABEL_ALLOW_HOST_FALLBACK=1 — an explicit escalation you choose, for code you have reviewed.
  3. dev_local permits intrinsic inspection commands only; project-code tests and builds are denied without Docker isolation. It is not a workaround for blocked coding runs.

There is no hidden flag that removes the isolation boundary, and this site will not suggest weakening it to make a tutorial succeed.

A session ended “unverified”

Section titled “A session ended “unverified””

An unverified-patch outcome means changes exist but authoritative verification did not substantively run. Run the project’s checks yourself and read Verification for what the outcome labels mean.

The TUI does not have /undo

Section titled “The TUI does not have /undo”

Recovery is intentionally split: use /checkpoint and /restore inside a session, or node .\babel-cli\dist\index.js undo from the CLI.

Where to inspect further

Section titled “Where to inspect further”
  • Session state and resume: node .\babel-cli\dist\index.js resume
  • The run’s tool activity and approvals: the TUI transcript itself
  • Deeper runtime reference: the Babel repository docs