Troubleshooting
Most day-to-day problems fall into a few patterns: the session expired, a model needs login, a skill is missing the secret it needs, or a surface lost its connection to the Engine. Use the table below to jump straight to the cause and the fix; then, if needed, collect a diagnostic.
Symptom → cause → fix
| Symptom | Likely cause | Fix |
|---|---|---|
| "Session expired" or a 401 error | The identity token expired or was revoked | Sign in again: /login (TUI/VS Code) or Sign in (Desktop). |
| "PolicyContext not configured — sign in again" | The session started without the org policy loaded | Sign in again to reload the policy. |
| "cloud API key is required for model nnumbers" (VS Code) | The login token didn't reach the Engine | Sign in through the extension (Imaginne: Login or /login). |
Skill asks for a missing secret (missing_required_env) | The org hasn't configured/attached the env-secret the skill declares | Ask the admin to create and attach the env-secret. See Skill env-secrets. |
| Skill doesn't appear or is refused | You don't have a profile that includes that skill | Ask the admin to assign it to your profile. See Profiles. |
| Voice unavailable | No microphone/permission, no org credential, or a build without the voice tag | Check the system permission, org enablement, and, on the TUI, the build. See Voice. |
| "Engine disconnected" (VS Code) | The extension couldn't spin up/reach the imaginne CLI | Run Imaginne: Run Health Check; if needed, set imaginne.binaryPath. |
| "requires a TTY-capable terminal" (TUI) | The TUI was started without an interactive terminal | Open it in a real terminal (not in a pipe or a TTY-less task). |
| Model blocked / empty model list | The org policy restricts the available models | Use nnumbers (default) or ask the admin. See Models. |
| "Too many concurrent runs" (web chat) | You have 10 runs active at once | Wait for one to finish or stop one with the stop button. See Web chat. |
| "Unsupported type" / "File larger than the limit" (web chat) | The attachment isn't in the accepted list or exceeds 50 MB | Convert or split the file. See Attachments & files. |
| "An attachment failed — remove it and send again" (web chat) | An attachment's upload didn't complete | Remove the failed chip and resend the message. |
| "Your storage is full" (web chat) | The account's 100 MB of files ran out | Delete files in the Files panel. See Attachments & files. |
| An old file shows as "unavailable" (web chat) | Its content is no longer stored | Ask the agent to generate the file again. |
| "Your memory storage is full" (web chat) | The account's 256 KB of memory ran out | Remove memories that no longer hold. See Account memory. |
Model needs login
Messages like "cloud API key is required for model nnumbers" (in VS Code) or authentication failures when calling the model almost always mean that login didn't reach the Engine — not that you need an API key. Imaginne uses your authenticated session (your organization login); you don't manage keys. Sign in again through the surface you're using. See Identity.
Skill missing an env or refused
Two distinct situations:
missing_required_env— the skill declares a secret (viarequired_env) that your organization hasn't configured yet. Only an admin can resolve it, by creating the env-secret and attaching it to the skill. See Env-secrets (admin).- Skill disappears from the list or is refused — you don't have a profile that grants access to that skill. Ask the admin to include it in your profile. With no profile at all, the chat stays empty. See Profiles.
Voice unavailable
If the microphone button (Desktop and web chat) or the Ctrl+G / F2 shortcuts (TUI) don't work, check in this order:
- Microphone permission — from the operating system (Desktop/TUI) or the browser (web chat).
- Voice credentials enabled by your organization.
- On the TUI, a build with the
voicetag (today, only the darwin-arm64 release). - In the web chat, a browser that supports audio recording — without it, the microphone button doesn't even appear.
Details in Voice.
Collect a diagnostic
When the problem persists, generate a diagnostic for yourself or to send to your organization's support.
- Desktop
- Terminal (TUI)
- VS Code
- Export Support Bundle — generates a redacted diagnostic package (no tokens or secrets). Use it to attach to support.
/fb <message>— sends feedback directly from the app, with session context.
/diagnostics— shows the configuration and connection state./feedback(or/fb) — sends feedback with context./statusand/whoamihelp confirm connection and identity.
- Imaginne: Run Health Check — checks whether the Engine is reachable and points out what to fix.
- Imaginne: Whoami — confirms your active identity.
The Desktop's Support Bundle and feedback (/fb) don't include your token or secrets. See Credentials to understand what never leaves your machine.
See also
Was this page helpful?
Report a problem on this pageDo not send passwords, keys, tokens, or customer data.