# Atlas error: Background subagents require ATLAS_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true > Export ATLAS_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true in the shell that launches Atlas and restart, or run the subagent in the foreground by omitting the background option. Atlas fails with Background subagents require ATLAS_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true because the task tool gates background execution behind an experimental runtime flag and fails the call rather than silently downgrading to a foreground run. The fix is to export ATLAS_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true in the shell that launches Atlas, if you accept the experimental behavior, and restart Atlas, since runtime flags are read at startup. Otherwise, run the subagent in the foreground by omitting the background option. ## Symptom Launching a background task fails with: Background subagents require ATLAS_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true. The subagent does not start, in the background or anywhere else. ## Cause The Atlas task tool gates background execution behind an experimental runtime flag and fails the call rather than silently downgrading to a foreground run, so an unset ATLAS_EXPERIMENTAL_BACKGROUND_SUBAGENTS produces a hard error. ## Fix 1. Export ATLAS_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true in the shell that launches Atlas, if you accept the experimental behavior. 2. Restart Atlas after setting the variable; runtime flags are read at startup. 3. Otherwise run the subagent in the foreground by omitting the background option. 4. Prefer several foreground task calls in parallel over one background job if you only need concurrency. ## Why does Atlas require ATLAS_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true Atlas requires ATLAS_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true because the task tool gates background execution behind an experimental runtime flag. In the 2026 build the tool fails the call rather than silently downgrading to a foreground run, so you always know which execution mode you got. The hard failure is a deliberate design choice. A silent downgrade would leave you believing a long job was running detached in the background while it was actually blocking your session, or finishing and reporting in a way you did not plan for. By refusing the call outright, Atlas keeps the contract explicit: you asked for a background subagent, and background subagents are experimental, so either you opt in with the flag or you pick a different execution mode. Atlas fans out work to subagents that can run in the foreground or in parallel background sessions, and the flag governs only the background half of that capability. ## How to enable background subagents in Atlas Enable background subagents in Atlas in 2 steps. First, export ATLAS_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true in the shell that launches Atlas, if you accept the experimental behavior. Second, restart Atlas, because runtime flags are read at startup and a variable set after launch has no effect on the running process. Set the variable in the same shell that starts Atlas, not in a different terminal or a shell that never spawns the process. If you launch Atlas from a desktop shortcut, a tmux pane, or an editor integration, the environment that matters is the one that actually spawns the binary, and exporting the flag in an unrelated login shell will not reach it. Persist the export in your shell profile if you want the behavior across sessions. Say the caveat out loud: the name contains EXPERIMENTAL for a reason, so opt in knowing the behavior may change. ## How to run an Atlas subagent in the foreground instead Run the Atlas subagent in the foreground by omitting the background option. Foreground subagents are not gated behind ATLAS_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true, so the task launches immediately with 0 environment changes and 0 restarts, which makes it the shortest path when you simply need the work done. Foreground is the right default for most work. The subagent runs, returns its result into the parent session, and the transcript stays coherent. Reach for foreground whenever the task is something whose answer you need before the next step, which is the majority of agent work: an exploration pass, a targeted search, or a scoped edit. Every Atlas tool call is permission-gated against allow, ask, and deny rules before it runs, and that gating applies to the subagent's tool calls whether it runs in the foreground or in the background, so choosing foreground costs you nothing in safety. ## How to get concurrency in Atlas without background subagents Prefer several foreground Atlas task calls in parallel over 1 background job when concurrency is all you need. Parallel foreground tasks require no runtime flag, no restart, and no opt-in to ATLAS_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true, and Atlas still fans the work out across multiple subagents. Concurrency and detachment are different needs, and the flag only governs detachment. If your goal is to search three parts of a repository at once, or to have several subagents investigate independent questions, issue multiple task calls and let them run together in the foreground. You get the parallelism without touching an experimental code path. Background execution earns its keep in a narrower case: a long-running job you genuinely want to detach from the conversation and collect later. If that is not what you are doing, foreground parallelism is the simpler answer. ## How to verify background subagents are enabled in Atlas Verify the Atlas fix in 2 moves: restart Atlas, then re-launch the background task. A task that starts without printing Background subagents require ATLAS_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true confirms the flag was read at startup and the experimental background path is now active. If the same error appears after you exported the variable, the running Atlas process did not see it. The two usual reasons are that Atlas was never restarted, since runtime flags are read at startup, or that the export happened in a shell other than the one that launches Atlas. Check the environment of the process itself rather than the shell you happen to be typing in. Once the flag is genuinely in the launching environment and Atlas has been restarted, the background task starts and the parent session continues while the subagent works. ## FAQ ### how to fix Background subagents require ATLAS_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true Export ATLAS_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true in the shell that launches Atlas and restart Atlas, since runtime flags are read at startup. Otherwise, run the subagent in the foreground by omitting the background option. ### why does Atlas fail instead of running the subagent in the foreground automatically The Atlas task tool gates background execution behind an experimental runtime flag and fails the call rather than silently downgrading to a foreground run, so the execution mode you asked for is never quietly changed. ### do I need to restart Atlas after setting ATLAS_EXPERIMENTAL_BACKGROUND_SUBAGENTS Yes. Restart Atlas after setting the variable, because runtime flags are read at startup and an already-running process will not pick up the new value. ### are background subagents in Atlas stable No. Background subagents are gated behind an experimental runtime flag, ATLAS_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true. Enable them only if you accept the experimental behavior. ### how do I run Atlas subagents in parallel without the experimental flag Prefer several foreground task calls in parallel over one background job if you only need concurrency. Foreground subagents are not gated behind the experimental flag. ### where should I export ATLAS_EXPERIMENTAL_BACKGROUND_SUBAGENTS In the shell that launches Atlas. A variable exported in an unrelated terminal never reaches the Atlas process, and the flag is read at startup. --- Canonical HTML: https://runatlas.sh/resources/troubleshooting/task-background-subagents-disabled Source of truth: aeo_pages row `/resources/troubleshooting/task-background-subagents-disabled` (segment: Troubleshooting) (this file is generated from it, never hand-edited). Licence: Atlas is proprietary with a free core. It is not open source and there is no public source repository.