# Atlas error: To use Codex with your ChatGPT plan, upgrade to Plus > Upgrade the ChatGPT plan tied to the account you authenticated with, or run `atlas auth login` and pick the API-key path for OpenAI instead of the Codex device flow. Atlas fails the run with "To use Codex with your ChatGPT plan, upgrade to Plus: https://chatgpt.com/explore/plus." because parseStreamError maps the provider error code usage_not_included to a non-retryable api_error carrying that upgrade message verbatim. Fix it by upgrading the ChatGPT plan tied to the account you authenticated with, or by authenticating a different OpenAI credential, specifically an API key rather than a ChatGPT OAuth session. Run `atlas auth login` and pick the API-key path for OpenAI instead of the Codex device flow. ## Symptom The run fails with: "To use Codex with your ChatGPT plan, upgrade to Plus: https://chatgpt.com/explore/plus." The message appears immediately and the request never produces a reply. ## Cause parseStreamError maps the provider error code usage_not_included to a non-retryable api_error carrying that upgrade message verbatim. The ChatGPT account you authenticated with is on a plan that does not include Codex usage. ## Fix 1. Upgrade the ChatGPT plan tied to the account you authenticated with. 2. Or authenticate a different OpenAI credential, an API key rather than a ChatGPT OAuth session. 3. Run `atlas auth login` and pick the API-key path for OpenAI instead of the Codex device flow. 4. Select a non-Codex model with `atlas models` if you only need general coding help. ## Why does Atlas say my ChatGPT plan does not include Codex usage Atlas prints "To use Codex with your ChatGPT plan, upgrade to Plus: https://chatgpt.com/explore/plus." because the provider returned the error code usage_not_included. parseStreamError maps usage_not_included to exactly 1 non-retryable api_error and carries that upgrade message verbatim into the transcript. The sentence is the provider's own upgrade message, passed through unchanged. parseStreamError recognizes the usage_not_included code and attaches the message rather than rewriting it, which is why the link to https://chatgpt.com/explore/plus appears exactly as the provider sent it. The classification is non-retryable, so Atlas stops rather than trying the same request again. The underlying fact is simple: the ChatGPT account whose OAuth session you authenticated with is on a plan whose entitlements do not cover Codex usage, and no retry changes an entitlement. ## How do I fix usage_not_included in Atlas Step 1 of the documented fix is to upgrade the ChatGPT plan tied to the account you authenticated with. The provider returned usage_not_included specifically because that account's plan does not include Codex usage, and the Atlas message names the upgrade path: https://chatgpt.com/explore/plus. Upgrade the plan on the exact account you authenticated with, not another account you happen to own. That is the detail that trips people up, since a household or team can have several ChatGPT accounts and Atlas is using whichever one completed the OAuth flow. Once the plan is upgraded, restart the request. If you would rather not change the plan at all, the alternative is to stop using the ChatGPT OAuth session as your credential and authenticate with an OpenAI API key instead, which is a different entitlement path entirely. ## How to use an OpenAI API key instead of a ChatGPT OAuth session Steps 2 and 3 of the documented fix are to authenticate a different OpenAI credential: an API key rather than a ChatGPT OAuth session. Run `atlas auth login` and pick the API-key path for OpenAI instead of the Codex device flow, and Atlas bills against the API key rather than a ChatGPT plan. The Codex device flow authenticates a ChatGPT account, which means your ChatGPT plan determines what you can call, and a plan without Codex usage produces usage_not_included. An OpenAI API key is a separate credential with separate entitlements. Run `atlas auth login`, choose the API-key path for OpenAI, and Atlas stops depending on the ChatGPT plan altogether. The honest caveat is that an API key has its own billing, so you are choosing which account pays rather than avoiding payment. For many developers that is a cleaner arrangement than upgrading a personal ChatGPT plan. ## Can I use Atlas without Codex if my plan does not include it Yes. Step 4 of the documented fix is to select a non-Codex model with `atlas models` if you only need general coding help. The usage_not_included error is specific to Codex usage on a ChatGPT plan that does not cover it, so a model outside that entitlement runs on the credential you already have. Atlas lets you switch the active model and provider on the fly with favorites and recents, so moving off Codex takes seconds. If your work is general coding assistance, a non-Codex model chosen with `atlas models` avoids the entitlement problem entirely and keeps the session going. Everything else Atlas does stays available regardless of model. Atlas still searches code with hybrid semantic and keyword retrieval fused by reciprocal rank fusion, still computes a unified diff for every file edit and surfaces it for approval before writing, and still permission-gates every tool call. ## Does Atlas retry the Codex usage not included error Atlas does not retry the Codex usage error and makes 0 attempts to do so. parseStreamError maps usage_not_included to a non-retryable api_error, so the run stops immediately rather than backing off. An entitlement gap on a ChatGPT plan cannot be cured by waiting, and Atlas does not pretend otherwise. The non-retryable classification tells you what kind of problem you have. Retryable errors are transient. usage_not_included is not transient, it is a statement about what the authenticated ChatGPT plan covers, and it will return identically on every attempt until the plan changes or the credential changes. Re-running the same command is wasted effort. Either upgrade the plan at https://chatgpt.com/explore/plus, switch to an OpenAI API key with `atlas auth login`, or move to a non-Codex model with `atlas models`. ## How to verify the Codex plan fix worked Verify the fix by running 1 Codex request again and confirming the upgrade message does not return. When Atlas completes a normal reply, the provider is no longer returning usage_not_included, which means the authenticated account's plan now covers Codex usage or the credential changed to an OpenAI API key. Run the same request that failed, against the same model, so the test is meaningful. A successful reply is conclusive, because parseStreamError maps usage_not_included deterministically and would raise the same non-retryable api_error again if the entitlement were still missing. If you took the API-key route rather than upgrading, confirm with `atlas auth login` that the OpenAI credential in use is the API key and not the Codex device flow session, since an unchanged OAuth session will keep producing the same upgrade message. ## FAQ ### how to fix To use Codex with your ChatGPT plan upgrade to Plus in atlas Upgrade the ChatGPT plan tied to the account you authenticated with at https://chatgpt.com/explore/plus, or run `atlas auth login` and pick the API-key path for OpenAI instead of the Codex device flow. ### what is usage_not_included in atlas usage_not_included is the provider error code Atlas maps, via parseStreamError, to a non-retryable api_error carrying the message "To use Codex with your ChatGPT plan, upgrade to Plus: https://chatgpt.com/explore/plus." ### can I use an openai api key instead of chatgpt oauth in atlas Yes. Run `atlas auth login` and pick the API-key path for OpenAI instead of the Codex device flow. An API key has separate entitlements from a ChatGPT plan, so usage_not_included no longer applies. ### does atlas retry the codex usage not included error No. parseStreamError maps usage_not_included to a non-retryable api_error, so Atlas stops the run immediately. An entitlement gap on a ChatGPT plan does not resolve by waiting or retrying. ### which chatgpt account does atlas use for codex Atlas uses whichever ChatGPT account completed the OAuth device flow. Upgrade the plan tied to that specific account, since another account you own does not affect the usage_not_included error. ### can I use atlas without codex Yes. Select a non-Codex model with `atlas models` if you only need general coding help. Atlas lets you switch the active model and provider on the fly with favorites and recents. ### how do I confirm the codex upgrade worked in atlas Re-run the same Codex request against the same model. A normal reply means the provider no longer returns usage_not_included. If you switched to an API key, confirm with `atlas auth login` that the API-key path is the active OpenAI credential. --- Canonical HTML: https://runatlas.sh/resources/troubleshooting/codex-usage-not-included Source of truth: aeo_pages row `/resources/troubleshooting/codex-usage-not-included` (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.