Troubleshooting

Find your symptom below and apply the fix. If nothing here matches, open the Feedback dialog from the HudShelf so we can reproduce it.

Symptom: The loading screen never goes away and the world map never appears.

Fix: Viberia’s local services failed to start. Quit the app completely, relaunch, and wait the full 5–10 seconds. If it still hangs:

1. Verify that you have at least one CLI provider installed and reachable (which claude, which codex, or which gemini from a terminal).
2. Check that no other Viberia process is already running — on macOS, look in Activity Monitor for any leftover processes and quit them.
3. Restart your machine and relaunch.

If the screen still hangs, file feedback with your OS version.

Symptom: “CLI binary not found” or a red error in Settings → CLI Configuration.

Fix: The path Viberia has on file points to a binary that doesn’t exist or isn’t executable.

1. From a terminal, run which claude (or codex / gemini) and copy the output.
2. Open Settings → CLI Configuration.
3. Paste the path into the corresponding field and click Test.
4. If which returned nothing, install the CLI from its official source and try again.

Symptom: The tutorial is stuck on a scene and won’t advance.

Fix: Reset and re-run the tutorial.

1. Open Settings → Tutorial.
2. Click Reset progress.
3. Click Re-run tutorial (or restart the app and the tutorial starts itself).

If the tutorial breaks again at the same scene, take the Quick path when offered — it uses a sandbox folder at ~/Viberia/Tutorial-Demo/ that avoids whatever local condition is tripping up the guided path.

Symptom: I sent a message to an agent and nothing happens — no streaming, no errors.

Fix: The agent’s CLI provider can’t be reached.

1. Open the Agent Window and check the mode cell that shows the model in use.
2. Switch the model temporarily to a different provider (e.g., Codex if you were on Claude) and resend the message.
3. If the alternate provider responds, go to Settings → CLI Configuration, click Test on the original provider, and fix the path or sign-in.
4. If neither provider responds, check Settings → Permissions — the default mode may be blocking the agent’s first tool call. Switch to Standard mode and watch for an Allow/Deny prompt the next time you send.

Symptom: “Queue full” or messages I send to an agent are being rejected.

Fix: Each agent has a FIFO queue of up to 200 messages. If the agent is stuck and not draining its queue:

1. Open the Queue Drawer from the HudShelf and inspect the queued messages for the agent.
2. Remove anything no longer relevant by dragging it out or clicking delete.
3. If the agent itself is unresponsive, click into its Agent Window and check whether a tool call is waiting for a permission prompt — if so, Allow or Deny it to unblock the agent.

See Queue Drawer for full controls.

Symptom: An MCP server I just added fails to start, and the agent reports it as unavailable.

Fix: Most MCP failures are due to missing credentials or a wrong command path.

1. Open the section where you added the server (Settings → MCP Servers for user-level, the Building Window → MCP tab for building-level, or the Agent Window → Settings → MCP tab for agent-level).
2. Verify the command field points to an executable that exists.
3. Verify any required environment variables (API keys, tokens) are set.
4. Click Restart on the server entry.

For canonical configs (Linear, filesystem, Postgres, Slack, Sentry, Brave Search, SQLite, Google Drive, git), re-run /learn-mcp in any agent chat and let it regenerate the entry. See MCP Servers.

Symptom: macOS says Viberia can’t access a folder, or files don’t appear after an agent completes a task.

Fix: Full Disk Access is not granted.

1. Open System Settings → Privacy & Security → Full Disk Access.
2. Confirm Viberia.app is in the list and toggled on. If it isn’t, click + and add it.
3. Quit and relaunch Viberia.
4. Verify in Settings → Permissions that Full Disk Access is shown as granted.

Symptom: The world map shows “resyncing…” and the panel won’t load.

Fix: A view-data sync didn’t complete. This is almost always transient.

1. Wait 5 seconds. Most resyncs clear themselves.
2. If it doesn’t clear, switch to another panel and back.
3. If the panel still won’t load, restart Viberia. View state rebuilds on launch.

If a specific panel resyncs forever across restarts, file feedback with the panel name.

Symptom: An agent says “missing API key” or asks me to sign in to a provider.

Fix: The CLI itself isn’t signed in. Viberia doesn’t store API keys — it relies on each provider’s CLI being signed in independently.

1. Open a terminal.
2. Run the provider’s sign-in command (e.g., claude login, codex login, gemini login — check the provider’s docs for the exact command).
3. Confirm with a small test prompt from the CLI directly.
4. Switch back to Viberia and resend the message.

Symptom: My project’s folder doesn’t seem to be where Viberia thinks it is, or the agent is editing files in the wrong place.

Fix: The project’s stored folder path is wrong.

1. Click the HQ building in the project.
2. In the Building Window, find the Folder path field.
3. Update it to the correct absolute path.
4. Close and reopen the project’s Agent Windows so they pick up the new working directory.

Symptom: The app feels sluggish on the world map; animations stutter.

Fix: Lower the graphics settings.

1. Open Settings → Graphics.
2. Change the Quality preset to Medium or Low.
3. If still sluggish, manually lower Water shader octaves and the FPS cap.
4. Reduce the Liquid-glass tier in Settings → Appearance — frosted glass effects can be expensive on integrated GPUs.

Still stuck?

Send feedback from the HudShelf with:

• Your OS and version
• A short description of what you were doing
• Which symptom above is closest

We triage feedback in the order it arrives.