# Atlas TUI error: Color reference not found in defs or theme, and Circular color reference > Open your theme file and define the missing name under defs, or point the reference at an existing color, then restart the TUI so both checks run again. The Atlas TUI fails to load a theme with Color reference "" 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. ## Symptom The Atlas TUI fails to load a theme with: Color reference "" not found in defs or theme. Or, when a reference chain loops back on itself: Circular color reference: a -> b -> a, with the full chain printed. ## Cause Theme resolution in Atlas walks color references through the theme's defs. An unknown name throws immediately, because there is nothing to resolve it to, and a reference chain that revisits a value throws a circular-reference error naming the whole chain rather than looping forever. ## Fix 1. Open your theme file and define the missing name under defs, or point the reference at an existing color. 2. For the circular case, read the printed chain and break the cycle by replacing one link with a literal color. 3. Validate that every reference resolves to either a def or another theme key, not to itself. 4. Restart the TUI, because both checks run at theme load time. 5. Confirm the theme loads with no Color reference or Circular color reference error. ## Why does the Atlas TUI say Color reference not found in defs or theme? The Atlas TUI reports Color reference "" 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 "" 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. ## FAQ ### 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. --- Canonical HTML: https://runatlas.sh/resources/troubleshooting/theme-color-reference-not-found Source of truth: aeo_pages row `/resources/troubleshooting/theme-color-reference-not-found` (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.