Troubleshooting and FAQ
Export
Start with Unity’s first Console error and the exact Atlas status message. Wait for compilation or a domain reload to finish before retrying a request.
Connection and setup
| Symptom | What to check | Next step |
|---|---|---|
| Atlas menu is missing | Import completion, duplicate Atlas copies, and Console errors | Resolve the first compilation error, then reopen the editor window. See Installation. |
| A product is missing | Supported version installed and compiled in this project | Open Atlas from that product’s menu and verify its package version. |
| Sign-in times out | Correct browser account and a current one-time connection | Start a fresh sign-in from Unity; do not reuse an old browser URL. |
| Purchase cannot be verified | Selected product, owning Opsive account, and matching invoice | Use the owning account or verify the correct invoice. Contact support if it still fails. |
| Local Codex is unavailable | Local installation, selected runtime route, sign-in, and executable path | Run Check Runtime & Sign-in in Atlas provider/runtime settings. |
| Claude Code is unavailable or signed out | Selected runtime route, installation and runtime sign-in | Choose Check Runtime & Sign-in, then Sign In to Claude Code if needed. Desktop-app sign-in alone is not sufficient. See Models and providers. |
| External assistant cannot connect | Matching Atlas package/service/plugin, enabled project connection, copied connection-file path | Reconnect to the intended project after compilation finishes. See AI assistants and skills. |
| API-key fields are absent | Client version, sign-in, and provider settings view | Update Atlas, sign in, and select Codex API or Claude API in Atlas Providers. Older services may still provide only local Codex models. |
| Key validation fails | Correct provider, valid key, provider access and billing | Check the provider account, then save the correct key in Atlas’s provider settings. |
| A model or effort is missing | Choices returned for the current provider/account | Select an offered choice; do not assume an example screenshot’s model is available. |
Unity project tools
| Symptom | Next step |
|---|---|
| Unity inspection cannot be enabled | Use Unity 6 or newer, install Unity CLI and Unity Pipeline in this project, and check Unity CLI executable. Ordinary prompts remain available without tools. |
| An isolated Codex sign-in error appears | Run Check Runtime & Sign-in and sign in through the installed Codex runtime. If sign-in cannot be used in the isolated session, turn off Unity project tools to continue without them. Do not paste login credentials into Atlas. |
| Atlas inspects but will not edit a scene | Enable the separate Allow Unity scene edits on explicit requests setting and explicitly describe a supported scene change. Leave Play Mode first. |
| Changing Provider in settings leaves the chat unchanged | This is expected. Select the active provider and model from the chat model dropdown. |
Requests and results
| Symptom | What to check | Next step |
|---|---|---|
| Request fails or stalls | Network connection, provider limits, Unity reload, and progress text | Let Unity become ready; use Retry request when offered. |
| Package build is incomplete | Whether the result offers Resume package build | Resume the existing build rather than applying a partial package. |
| Attachment is rejected | Selected provider/model, five-attachment limit, file size, UTF-8 text encoding, and cached-file availability | Choose a compatible model, reduce the file, or remove and reattach it. See Providing context. |
| Atlas describes the wrong graph | Active product, attached owner, and current graph snapshot | Attach the intended graph and state the exact node or transition. |
| A file cannot be modified | Compatible user-authored target selected in the Project window | Select the intended source; installed package/vendor files are not editable targets. |
| Saving is blocked | Destination, existing file, access setting, and instruction scope | Choose a valid Assets/... destination and review any confirmation or scope warning. |
| Code fails to compile | Exact diagnostic, product version, and unrelated Console errors | Use the offered correction flow or provide the diagnostic in the same chat. |
| Code compiles but does not work | Inspector assignments, lifecycle, graph wiring, start conditions, and ownership | Reproduce in a small test setup and report expected versus actual behavior. |
Common questions
Does Atlas build the whole graph for me?
Generating task, Action, or Condition source creates types you can add to a graph. You still assemble the graph and configure its references through the product editor. Ask Atlas to explain that setup as part of the plan.
Can I keep using local Codex after adding a key?
Yes. API-key routes and the local Codex route are separate model choices. Check the selected provider before sending a request. See Models and providers.
Does clearing a chat delete server history?
No. It clears the local working conversation. See Privacy and project data for storage and deletion distinctions.
Why did Atlas recommend a built-in object instead of generating a file?
Atlas prefers a supported built-in object when it already satisfies the request. Explain the specific missing behavior if you need a custom implementation.
Send a useful support report
Include the Unity version, Opsive product and version, Atlas package version, operating system, selected provider route, exact error text, and concise reproduction steps. Say whether the failure occurred during sign-in, generation, application, compilation, or Play Mode. Include a request identifier when Atlas displays one.
Use a small sanitized example or screenshot. Do not send API keys, Codex credentials, one-time connection URLs, or a whole private project by default. The development-only verbose diagnostics menu is not present in ordinary customer builds.
Contact Opsive through the Support page.