Atlas exits with Configuration is invalid at <config path>: bad file reference: "{file:...}" <resolved path> does not exist because config/variable.ts expands `{file:...}` tokens by reading the referenced path relative to the config directory, and throws ConfigInvalidError on ENOENT naming both the token and the resolved absolute path. The fix is to check the resolved path printed in the message, remembering that relative tokens resolve against the config file's directory and not your cwd, then create the referenced file or correct the path inside the token.
Why does Atlas say bad file reference: "{file:...}" does not exist?
Atlas says bad file reference: "{file:...}" <resolved path> does not exist because config/variable.ts expands `{file:...}` tokens by reading the referenced path and throws ConfigInvalidError on ENOENT. The message names 2 things: the token you wrote, and the absolute path Atlas actually resolved it to.
A `{file:...}` token in an Atlas config is an instruction to read another file and inline its contents. config/variable.ts performs that expansion during config load. When the read fails with ENOENT, meaning the file is not there, Atlas does not quietly expand the token to an empty string. Atlas throws ConfigInvalidError and prints Configuration is invalid at <config path> with the bad file reference detail. Both halves of the message matter: the token shows what you asked for, and the resolved path shows where Atlas looked.
Why does the resolved path look wrong in Atlas?
The resolved path in an Atlas bad file reference is computed against 1 directory only, the directory holding the config file, not your current working directory. config/variable.ts expands `{file:...}` tokens relative to that config directory, so a token that works from your shell can still resolve somewhere unexpected.
The cwd assumption is the single most common source of this error. A relative token such as one pointing at a file one directory up is resolved against the directory that holds the config file, not against wherever you happened to launch Atlas from. That is why the resolved absolute path in the message can name a location you never intended. Read the resolved path literally. If it points somewhere surprising, the token is relative to the wrong anchor, and correcting the path inside the token is the fix rather than moving your shell.
How to fix a bad file reference in an Atlas config
Fix an Atlas bad file reference in 2 moves: create the referenced file, or correct the path inside the `{file:...}` token. Check the resolved path printed in the message first, because config/variable.ts resolves relative tokens against the config file's directory rather than your cwd.
Deciding between the two moves is straightforward. If the file was supposed to exist and simply has not been created yet, create it at the resolved path Atlas printed. If the file exists somewhere else, the token is pointing at the wrong place, so correct the path inside the token so it resolves against the config file's directory to the real location. Do not do both. Creating a stub at a path you never intended leaves a phantom file that will confuse the next person to read the config.
How to make a file reference optional in Atlas
To make an Atlas file reference optional, use the missing: "empty" behavior, step 3 of the documented fix, so an absent file expands to an empty string instead of failing. Without it, config/variable.ts throws ConfigInvalidError on ENOENT and Atlas refuses to start at all.
Optional references are legitimate. A config that inlines a local overrides file, or a machine-specific fragment that only some developers have, should not hard-fail on machines where the file is absent. The missing: "empty" behavior is the documented way to express that: the token expands to an empty string and startup proceeds. The caveat is worth stating plainly, because it is easy to reach for missing: "empty" as a way to silence the error. If the file is genuinely required, silencing the error just moves the failure downstream to whatever consumed the now-empty value.
Does a bad file reference stop the rest of the Atlas config?
Yes. A bad file reference stops Atlas at Configuration is invalid at <config path>, and none of the remaining config is applied on that run. config/variable.ts throws ConfigInvalidError during expansion, so 1 `{file:...}` token pointing at a path that does not exist halts the entire load.
Token expansion happens as part of loading the config, so an ENOENT on one reference takes the whole file with it. Nothing after the failing token is applied, which means a valid config with one dead reference behaves exactly like a broken config. Fix the reference or mark it optional with missing: "empty", then re-run Atlas. Atlas indexes code by AST declarations using tree-sitter, not blind line windows, and the settings that drive that indexing often live in the same config file, so a dead token can silently cost you the behavior you expected.
How to verify the file reference fix worked in Atlas
Verify the Atlas file reference fix by re-running Atlas, step 4 of the documented fix. A start with no bad file reference message means config/variable.ts expanded every `{file:...}` token successfully, and each referenced file was readable at the path resolved against the config directory.
Re-running Atlas is the verification, because config/variable.ts expands the tokens on every load. If the same resolved path appears again in the error, the file was created somewhere other than where Atlas is looking, and the resolved absolute path in the message is the authority on where that is. If a different token now fails, the first reference is fixed and Atlas has simply moved on to the next `{file:...}` expansion in the config.
How to fix it
- 01Check the resolved path printed in the message, because relative tokens resolve against the config file's directory, not your cwd.
- 02Create the referenced file, or correct the path inside the token.
- 03If the file is optional, use the missing: "empty" behavior so an absent file expands to an empty string instead of failing.
- 04Re-run Atlas.
- 05Confirm startup completes with no bad file reference message.
Frequently asked questions
- How do I fix bad file reference in Atlas config?
- Check the resolved path printed in the message, then create the referenced file or correct the path inside the `{file:...}` token. Relative tokens resolve against the config file's directory, not your cwd, which is why the resolved path may not be where you expected.
- Why does my Atlas {file:...} token resolve to the wrong path?
- config/variable.ts expands `{file:...}` tokens by reading the referenced path relative to the config directory. A relative token is therefore anchored to the directory holding the config file, not to your current working directory.
- Can an Atlas file reference be optional?
- Yes. Use the missing: "empty" behavior so an absent file expands to an empty string instead of failing. Without it, config/variable.ts throws ConfigInvalidError on ENOENT and Atlas exits with bad file reference.
- What does ENOENT mean in an Atlas config file reference?
- ENOENT means the file the `{file:...}` token points at does not exist at the resolved path. config/variable.ts throws ConfigInvalidError on ENOENT and names both the token and the resolved absolute path in the message.
- Does Atlas start if only one file reference is broken?
- No. config/variable.ts throws ConfigInvalidError during expansion, so a single bad `{file:...}` token stops the config load and Atlas exits with Configuration is invalid at <config path>. Fix the reference or mark it optional with missing: "empty".
- How do I confirm the Atlas file reference is resolved?
- Re-run Atlas. A start with no bad file reference message means every `{file:...}` token expanded and each referenced file was readable at the path resolved against the config directory.
Try Atlas in your terminal
The terminal-native AI coding agent. Free core, single binary.
Install AtlasRelated guides
Atlas with DeepSeek V4 Flash: The Cheapest 1M Context Reasoning Model in 2026
DeepSeek V4 Flash in Atlas: $0.14 / $0.28 per Mtok on a 1M window with 384,000 output tokens, or $0.09 / $0.18 via DeepInfra. Setup, small_model wiring, tradeoffs.
Atlas with Gemini 2.0 Flash: A Fast Reader With an 8,192 Token Output Cap in 2026
Gemini 2.0 Flash in Atlas: the December 2024 release with a 1,048,576 token context, $0.1 per Mtok input, no reasoning mode, and an 8,192 token output ceiling.
Atlas with Llama 3.3 8B Instruct (Meta Llama API): The small_model Slot in 2026
Llama 3.3 8B Instruct (Meta Llama API) in Atlas for 2026: 128,000 tokens of context in an 8B-class model, a 4,096 token output cap, and why it belongs in small_model.
Atlas vs Poolside: Terminal AI Coding Agents in 2026
Compare Atlas and Poolside, two terminal AI coding agents in 2026. Atlas offers a free core and robust safety features, while Poolside provides open-weight Laguna models and on-prem deployment options.
Atlas with GPT-OSS 20B (hosted): the cheap slot that can still think in 2026
Run Atlas on GPT-OSS 20B (hosted) in 2026: $0.03/$0.14 per Mtok on DeepInfra, a 131,072 token context, reasoning on, and $0.00/$0.00 locally in LM Studio.
Atlas with OpenCoder 8B (Ollama): the Auditable Local Coder in 2026
OpenCoder 8B (Ollama) runs Atlas on a fully open code LLM: open data, open recipe, 4.7GB, 8K tokens (8,192) of context, Free (self-hosted). Setup and tradeoffs.
Atlas with Qwen Flash: A Cheap Tier That Still Writes Real Diffs in 2026
Run Atlas on Qwen Flash in 2026. Alibaba's fast tier pairs 1M tokens (1,000,000) of context with a 32,768 token output at $0.05 per Mtok in, $0.40 per Mtok out.
Atlas for PyTorch: Terminal-Native AI Coding for nn.Module, Devices, and Autograd in 2026
Atlas is a terminal-native AI coding agent for PyTorch in 2026, where device placement, autograd, and DataLoader worker counts cause most bugs and most slowness.