Troubleshooting

Most problems fall into a handful of cases, starting with the connection ones.

`401 Unauthorized`

The connection isn’t authenticated.

API-key setups — the key is wrong, expired, or revoked. Check you pasted the full oc_live_… value, and that it hasn’t been revoked in World Settings → API Connections. Create a new key if needed.
Connector (sign-in) setups — your access was revoked or the sign-in expired. Reconnect the tool and sign in again. Confirm the app still appears on the portal’s Connected AI and Apps page.

`404 Not Found`

The world URL doesn’t resolve. On a single-world connection, check the world ID in the URL — it’s the UUID shown in the portal address bar when you’re inside the world (…/worlds/<world_id>/…). A 404 can also mean the world no longer exists.

Tools are missing

The agent only sees tools its access allows.

Read-only access — write tools (create/update/delete) won’t appear. Use a read-write API key, or check that your role on the world is editor or owner (viewers are read-only).
Connector, no world active — until a world is selected, only the world-listing/switching tools show. Ask the agent to list your worlds and switch to one. See The connector.

The agent can’t switch to a world, or says it isn’t granted

On the connector, an agent can only reach worlds in the app’s grant — the set you approved for that app at sign-in (and can edit later). If a world is missing or switching fails:

Not granted yet — add the world to the app on the portal’s Connected AI and Apps page (an app can hold up to 32 worlds).
Granted but still unreachable — the connection may be carrying the older grant. Reconnect the MCP client (disconnect and reconnect, or sign in again) so it picks up the change.
The world shows a warning on Connected AI and Apps — you’ve lost access to it yourself (for example, your collaborator role was removed); that has to be restored before the app can use it.
No world active — until one is selected, only the listing/switching tools appear. Ask the agent to list your worlds and switch to one.

Rate-limit errors (`429`), or hitting another limit

Each plan caps how many MCP requests per minute a user can make against a world. If an agent is making rapid calls, slow it down or move the world to a higher plan. Entity and seat limits work the same way — they’re set by the plan, and upgrading raises them.

The connection won’t establish

stdio bridge (mcp-remote) — make sure Node.js 18+ is installed and on your PATH.
Config not picked up — fully quit and reopen the client after editing its config (closing the window often isn’t enough).
Reachability — cloud clients (Claude’s connectors, ChatGPT) reach Orbismo over the public internet; that’s fine for app.orbismo.com, but a locally bridged setup needs the machine running the bridge to have internet access.

Changes aren’t showing in the portal

The portal doesn’t live-update. Refresh the page and the agent’s changes will appear.

The agent is working from stale data

The reverse problem: an AI tool keeps everything it has already read in its conversation context, and it will often answer from that snapshot instead of re-querying Orbismo — nothing tells it the world changed underneath. Working alone you’ll rarely notice; in a collaborative world, where someone else (or their agent) may be writing at the same time, it shows up as answers that miss a collaborator’s recent edits, duplicates of entities someone else just created, or updates that overwrite changes the agent never saw.

What helps:

Ask it to re-pull. “Re-read that entity from Orbismo first” — an explicit request beats waiting for the agent to decide.
Start a fresh session when you come back after a break. Everything in an old conversation is a snapshot from when it was read.
In collaborative worlds, make it a standing rule. Add a line to the world instructions: “Before creating or updating anything, re-search or re-read it first — treat anything earlier in this conversation as possibly out of date.”

“I can’t edit entities or lore in the portal”

That’s expected — the portal is for browsing and managing; you create and edit content by connecting an AI tool and asking it to make the change. See Entities and relationships.

Didn’t get a verification or magic-link email? Check spam, then request a new one — the links expire after a while.
Locked out after a password reset? Resetting your password signs out all sessions; sign in again with the new password. See Sign-in methods.

Can’t access a world

Worlds are private to their owner and invited collaborators. If you can’t see a world someone mentioned, ask its owner to invite you. If a world you had access to disappeared, your collaborator role may have been removed.

Billing and plans

Cancellations, refunds, failed payments, and blocked downgrades are covered in the Billing FAQ and Upgrade or downgrade.

Still stuck? Re-check the connection model in Connect an AI tool — and if the problem persists, contact support.