Troubleshooting

Signed out or sign-in expired

A sign-in lasts 30 days and renews each time your AI tool uses it. If it lapses, or you signed out, the MCP server answers 401 Authentication required and your AI tool shows the connector as disconnected or asks you to sign in.

Reconnect the connector in your AI tool and sign in again. In Claude Code, run /mcp and choose the OpenKnowledge server to authenticate.

A tool call that fails with connection-unauthorized, or project-action-credential ("Sign in again or re-authorize your client to access this project."), needs the same fix. Nothing was changed.

A client that asks for scopes other than openid, profile, email and offline_access gets invalid_scope. Remove the extra scopes from the client's configuration and connect again.

"Unknown project"

No reachable project is named `example-project`. Call `projects` for the names you can use.

The name you passed as project is not one of the brains your account can open. Ask your AI tool to call the projects tool, then use a name or qualifiedName (scope/name) from its list. If the brain you want is missing, check that you signed in with the right account and that someone added you to the brain.

ambiguous-project means two brains share that name. Use the qualifiedName instead.

Permission refused

This action needs edit access. Ask a project Owner or Editor to grant it.

The error code is project-action-permission. Your role in that brain does not allow the change; for example, a Viewer cannot edit files. Nothing was changed. The message names the access you need (view, comment, edit or share). Ask an Owner or Editor of the brain to give it to you.

If the message is "Only a project Owner can do this.", the change is one only an Owner can make, such as managing Owners. Ask an Owner of the brain.

If the message is "This workspace is read-only until a workspace owner subscribes in Billing.", the workspace has no active subscription. A workspace owner can fix it in the workspace's Billing settings.

Version conflict when writing

OpenKnowledge Cloud refuses to replace text an agent has not read, so it never silently overwrites someone else's edit.

Refused: this command would replace notes/plan.md using a version it has not read, risking unseen edits. Read it before replacing it; after an append, read it again in the same command. For a replacement without a preceding append, you can instead pass `base` with the `version` from an earlier read. Nothing was applied.

The code is overwrite-unread. To fix it, have the agent read the file with exec first, then write it again. Or pass base: the version the earlier read reported for that file, keyed by path, such as { "notes/plan.md": "<id>:<n>" }. OpenKnowledge merges the write with any edits made since that version.

Other conflict codes:

• project-changed: someone else changed the file while the command ran. Run it again.
• base-unreadable: the base version passed could not be read. Read the file again and use its current version.
• duplicateOf in the result: the connection just ran this exact command, so it did not run again. Pass rerun: true only if you meant to apply it twice.

Busy or unavailable

project-busy ("The project is busy, so nothing ran. Retry shortly."), api-unavailable and api-rate-limited mean nothing was applied. Wait a few seconds and try again.

Report a bug

• In the app: choose Help > Report a bug… (Cmd+Shift+D or Ctrl+Shift+D), or run Report a bug from the command palette. The report goes to the OpenKnowledge team.
• By email: write to support@inkeep.com.

Say which AI tool you used, what you asked it to do, and the error code and message it showed. If you call the MCP server yourself, include the x-request-id header from the response: OpenKnowledge Cloud uses it to find the call in its records.