The Atlas TUI fails to load a theme with Color reference "<value>" not found in defs or theme when a color name does not resolve, and with Circular color reference: a -> b -> a when a reference chain revisits a value. Theme resolution in Atlas walks color references through the theme's defs, so an unknown name throws immediately and a cycle throws an error naming the whole chain. The fix is to define the missing name under defs, or to break the cycle by replacing one link with a literal color.
Why does the Atlas TUI say Color reference not found in defs or theme?
The Atlas TUI reports Color reference "<value>" not found in defs or theme because theme resolution walks color references through the theme's defs, and 1 unknown name throws immediately. Open your theme file and define the missing name under defs, or point the reference at an existing color.
A color reference in an Atlas theme is a name that must resolve to something: either an entry in the theme's defs block, or another key in the theme itself. Theme resolution walks those references at load time. When a name matches neither, there is nothing left to resolve it to, so Atlas throws rather than falling back to a default color you did not ask for. The message quotes the exact unresolved value, which is usually enough to spot a typo or a def you meant to add and never did.
What does Circular color reference: a -> b -> a mean in Atlas?
Circular color reference: a -> b -> a means an Atlas theme reference chain revisits a value it already passed through, here after 2 hops. Theme resolution walks references through the theme's defs, detects the repeat, and throws naming the whole chain so you can see which links form the loop.
Naming the chain is the useful part of the error. A cycle across two entries is easy to spot by eye, but a longer chain that winds through several defs before returning to its start is not, and the printed chain tells you every link. Read it left to right and pick a link to break. Replacing one link with a literal color ends the loop, because a literal resolves without walking anywhere. The Atlas TUI has no way to guess which link you meant to be the concrete one, which is why the error asks you to decide.
How to fix a broken color reference in an Atlas theme
Fix a broken Atlas color reference in 1 edit: open your theme file and define the missing name under defs, or point the reference at an existing color. Theme resolution walks references through the theme's defs, so a name that exists in defs resolves and the TUI loads the theme.
Two paths work, and which one is right depends on intent. If the name was supposed to be a shared color, add it to defs, and every reference to it resolves at once. If the name was a typo for a color that already exists, point the reference at that existing color instead of creating a duplicate def. Atlas ships a TUI theme system with a charcoal-and-blue default theme and many presets, so if your custom theme is fighting you, switching to a preset is a legitimate way to get a working TUI while you repair the file.
How to break a circular color reference in Atlas
Break an Atlas circular color reference by replacing 1 link in the printed chain with a literal color. The Circular color reference: a -> b -> a error names the whole chain, so pick the link that should have been concrete and give it a real color value instead of another reference.
Choosing the right link to break is a design decision, not a mechanical one. Look at the chain Atlas printed and ask which entry is conceptually the source color, the one everything else is meant to derive from. That entry is the one that should hold a literal color. The others can keep referencing it. After the edit, validate that every reference resolves to either a def or another theme key, not to itself, since a self-reference is the shortest possible cycle and produces the same class of error.
When does Atlas check theme color references?
Atlas checks theme color references at theme load time, and 2 checks run there: the unknown-name check and the circular-reference check. Both fire when theme resolution walks the references, which is why the errors appear during load rather than while the TUI is running, and why a restart is required.
Load-time validation means edits do not take effect until the Atlas TUI reloads the theme. Restart the TUI after every change to the theme file, and read the error fresh rather than assuming an old message still applies. A different error after a restart is progress: resolving the unknown name can reveal a cycle further down the chain that theme resolution never reached before. Work through them one restart at a time until the TUI loads the theme with neither error.
How to verify the Atlas theme fix worked
Verify the Atlas theme fix by restarting the TUI, since both checks run at theme load time. A load with 0 errors, no Color reference "<value>" not found in defs or theme and no Circular color reference message, means every reference resolved through the theme's defs.
Restarting the Atlas TUI is the verification, and there is a useful intermediate signal. If the unknown-name error is replaced by a circular-reference error, the missing def is now defined and theme resolution has walked further into the chain than it could before. Keep going. Confirm at the end that every reference resolves to either a def or another theme key, not to itself, and that at least one link in each chain holds a literal color so resolution has somewhere to terminate.
How to fix it
- 01Open your theme file and define the missing name under defs, or point the reference at an existing color.
- 02For the circular case, read the printed chain and break the cycle by replacing one link with a literal color.
- 03Validate that every reference resolves to either a def or another theme key, not to itself.
- 04Restart the TUI, because both checks run at theme load time.
- 05Confirm the theme loads with no Color reference or Circular color reference error.
Frequently asked questions
- How do I fix Color reference not found in defs or theme in the Atlas TUI?
- Open your theme file and define the missing name under defs, or point the reference at an existing color. Theme resolution in Atlas walks color references through the theme's defs, and an unknown name throws immediately at theme load time.
- What causes Circular color reference in an Atlas theme?
- A reference chain that revisits a value causes it. Atlas throws a circular-reference error naming the whole chain, such as Circular color reference: a -> b -> a. Break the cycle by replacing one link with a literal color.
- Can an Atlas theme color reference point at another theme key?
- Yes. Every reference must resolve to either a def or another theme key, and never to itself. A self-reference is the shortest possible cycle and produces the circular-reference error at theme load time.
- Why does my Atlas theme edit not take effect?
- Both the unknown-name check and the circular-reference check run at theme load time, so restart the TUI after editing the theme file. Until the Atlas TUI reloads the theme, the previous resolution is still in effect.
- Do I have to write a custom Atlas theme at all?
- No. Atlas ships a TUI theme system with a charcoal-and-blue default theme and many presets, so switching to a preset gives you a working TUI while you repair a custom theme file that fails to resolve its color references.
- Why did a new theme error appear after I fixed the first one?
- Resolving an unknown color name lets theme resolution walk further along the reference chain, where it can then detect a cycle it never reached before. A different error after a restart means progress, so read the newly printed chain and break the cycle.
Try Atlas in your terminal
The terminal-native AI coding agent. Free core, single binary.
Install AtlasRelated guides
Atlas with Claude Opus 4.6: Setup, Cost, and Tradeoffs in 2026
Claude Opus 4.6 gives Atlas a 1M token context at $5 per Mtok input, $25 per Mtok output. Setup steps, cost math, and when to pick a newer Opus instead.
Atlas with Claude Opus 4.1: The Pre Price Cut Opus in 2026
Claude Opus 4.1 runs Atlas on a 200K context at $15 per Mtok input, $75 per Mtok output, with a 32K output ceiling. Setup, cost warnings, and better alternatives.
Atlas with Qwen2.5 7B Instruct in 2026: The Cheap Dense Small Model
Qwen2.5 7B Instruct runs Atlas's small_model slot at $0.175 per Mtok input and $0.70 per Mtok output, keeping the full 131,072 token window on a dense 7B checkpoint.
Atlas with Amazon Nova 2 Lite: Cost, Context, and Setup in 2026
Amazon Nova 2 Lite drives Atlas from inside your AWS account at $0.33 / $2.75 per Mtok with a 128K context. Setup, real tradeoffs, and when to pick another model.
Atlas with GitHub Models in 2026: Free Model Access Behind a GITHUB_TOKEN
Run Atlas on GitHub Models in 2026: every model listed at $0/$0 per Mtok, auth with the GITHUB_TOKEN you already have, and 256,000 tokens on AI21 Jamba 1.5 Large.
Atlas for Three.js: Terminal-Native AI Coding for Scenes, Materials, and Disposal in 2026
Atlas is a terminal-native AI coding agent for Three.js in 2026, where geometry, material, and texture disposal is the difference between a demo and a leak.
Run Atlas Headless in CI with Atlas (2026 Workflow)
How to run Atlas headless in CI in 2026: atlas run sends one prompt and exits when the session goes idle, with --format json, --command, and --continue for pipeline steps.
Atlas with MiniMax-M2.5-highspeed in 2026: Paying 2x for Latency
MiniMax-M2.5-highspeed runs Atlas at $0.60 per Mtok input and $2.40 per Mtok output, exactly double base M2.5, for identical weights and a 204,800 token context.