# Atlas error: Configuration is invalid, Unrecognized key in config > Remove or rename the key named in the Unrecognized key issue, and check its spelling and casing against the documented schema, because keys are matched exactly. Atlas exits with Configuration is invalid at and an issue line reading Unrecognized key: because config/parse.ts computes topLevelExtraKeys against the schema and throws ConfigInvalidError with an unrecognized_keys issue before decoding. The fix is to remove or rename the key named in the issue, check its spelling and casing against the documented schema, and nest a provider or MCP entry under `provider` or `mcp` rather than leaving it at top level. A typo in a top-level field is caught explicitly instead of being silently ignored. ## Symptom Atlas exits with: Configuration is invalid at , followed by an issue line reading Unrecognized key: , or Unrecognized keys: a, b when more than one top-level field is not in the schema. ## Cause config/parse.ts computes topLevelExtraKeys against the schema and throws ConfigInvalidError with an unrecognized_keys issue before decoding. A typo in a top-level field is therefore caught explicitly instead of being silently ignored, which is why Atlas refuses to start rather than skipping the key. ## Fix 1. Remove or rename the key named in the issue, and check spelling against the documented schema. 2. Watch for casing, because keys are matched exactly. 3. If you meant to add a provider or MCP entry, nest it under `provider` or `mcp` rather than at top level. 4. Re-run Atlas, because the remaining schema issues are reported all at once (decode runs with errors: "all"). 5. Confirm startup completes with no Configuration is invalid message. ## Why does Atlas say Unrecognized key in my config? Atlas says Unrecognized key: because config/parse.ts computes topLevelExtraKeys against the schema and throws ConfigInvalidError with an unrecognized_keys issue before decoding. In 2026 a top-level field that is not in the schema is treated as a typo worth stopping for, not an extra key to ignore. Many tools ignore unknown configuration keys, which means a typo silently does nothing and you spend an afternoon wondering why a setting had no effect. Atlas takes the opposite position. config/parse.ts compares the top-level keys in your config against the schema, collects the ones that do not belong as topLevelExtraKeys, and throws ConfigInvalidError with an unrecognized_keys issue before it even attempts to decode the rest. The result is that Configuration is invalid at arrives immediately, and the issue line names the exact key at fault. ## How to fix Configuration is invalid at in Atlas Fix Configuration is invalid at in Atlas by removing or renaming the key named in the Unrecognized key issue, which is step 1 of the 5 documented steps, then checking its spelling against the documented schema. Watch casing carefully, because Atlas matches config keys exactly. Read the issue line first, since Atlas names the offending key directly: Unrecognized key: , or Unrecognized keys: a, b when more than one is wrong. Decide whether the key was a typo of a real field, in which case rename it, or whether it does not belong at all, in which case delete it. Exact matching means near misses do not count. A key that differs only in casing from a schema field is still unrecognized, and Atlas will keep refusing to start until the casing matches what the schema declares. ## Why does casing matter in Atlas config keys? Casing matters in Atlas config keys because keys are matched exactly against the schema. config/parse.ts computes topLevelExtraKeys with no case-insensitive fallback, so in 2026 a key that differs by 1 capital letter still lands in the unrecognized_keys issue and Atlas throws ConfigInvalidError before decoding. Exact matching is a deliberate choice and it does trip people up, so it is worth saying plainly: Atlas will not quietly accept a key whose capitalization is off. If the schema declares a field in one form, that is the only form config/parse.ts recognizes. When an Unrecognized key issue names something that looks correct at a glance, compare it character by character against the documented schema rather than assuming Atlas is confused. The mismatch is usually a capital letter or an underscore where the schema wants something else. ## Should provider and MCP entries be top-level keys in Atlas config? Provider and MCP entries do not belong at the top level of an Atlas config. Nest the entry under 1 of the 2 declared parents, `provider` or `mcp`, otherwise config/parse.ts records the name in topLevelExtraKeys and throws an unrecognized_keys issue before decoding ever runs. A common shape of this failure is adding the name of a provider, or the name of an MCP server, as a bare top-level field. The schema does not declare arbitrary top-level names, so config/parse.ts flags them and Atlas exits with Configuration is invalid at . Nest the entry under `provider` or `mcp` and the key is validated in the right place instead. Atlas connects to Model Context Protocol servers and exposes their tools to the agent, so MCP servers are configured, just not at the top level of the file. ## Does Atlas report every config issue at once? Atlas reports the remaining schema issues all at once, because decode runs with errors: "all". Validation happens in 2 phases, though: the unrecognized_keys issue is thrown by config/parse.ts before decoding, so a top-level typo can surface on its own and other schema issues appear only on the next run. The two-phase behavior explains a fix cycle that can feel repetitive. First config/parse.ts checks topLevelExtraKeys against the schema and throws ConfigInvalidError if anything is unrecognized. Only once that check passes does decode run, and decode is configured with errors: "all", so it reports every remaining schema issue in one pass rather than one per run. Practically, that means you may fix an Unrecognized key, re-run Atlas, and see a fresh batch of unrelated schema issues. Nothing is wrong. Atlas is simply showing you the next phase of validation. ## How to verify the Atlas config validates again Verify the Atlas config fix by re-running Atlas after removing or renaming the unrecognized key. A start with no Configuration is invalid at message means both phases passed: config/parse.ts found 0 topLevelExtraKeys, and decode, running with errors: "all", found nothing left to report. Re-running Atlas is the whole verification, since config/parse.ts evaluates the config on every start. If the Unrecognized key issue is gone but new schema issues appear, the top-level typo is fixed and Atlas has simply advanced to decoding, where errors: "all" reports the rest in one batch. If the same key is still named, check for a second copy of the config: Atlas prints the path in Configuration is invalid at , and that path is the file to edit, not the one you assume you edited. ## FAQ ### How do I fix Unrecognized key in Atlas config? Remove or rename the key named in the issue and check spelling against the documented schema. Atlas computes topLevelExtraKeys in config/parse.ts and throws ConfigInvalidError with an unrecognized_keys issue, so the key must either match the schema exactly or be deleted. ### Why does Atlas fail instead of ignoring an unknown config key? config/parse.ts throws ConfigInvalidError with an unrecognized_keys issue before decoding, so a typo in a top-level field is caught explicitly instead of being silently ignored. Atlas would rather stop than let a misspelled setting quietly do nothing. ### Are Atlas config keys case sensitive? Yes. Keys are matched exactly, so a key that differs only in casing is reported as an Unrecognized key and Atlas exits with Configuration is invalid at . Compare the key character by character against the documented schema. ### Where do provider and MCP entries go in an Atlas config? Nest them under `provider` or `mcp` rather than at top level. A provider or MCP entry placed at the top level is recorded in topLevelExtraKeys by config/parse.ts and reported as an unrecognized key. ### Does Atlas show all config errors at once? The remaining schema issues are reported all at once, because decode runs with errors: "all". The unrecognized_keys issue is thrown before decoding, though, so a top-level typo can surface by itself and other issues appear on the next run. ### What is ConfigInvalidError in Atlas? ConfigInvalidError is the error Atlas throws from config/parse.ts when the config does not satisfy the schema. For a top-level typo, it carries an unrecognized_keys issue and the CLI prints Configuration is invalid at along with the offending key name. --- Canonical HTML: https://runatlas.sh/resources/troubleshooting/config-unrecognized-keys Source of truth: aeo_pages row `/resources/troubleshooting/config-unrecognized-keys` (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.