# Troubleshooting

The errors below come back as JSON inside the tool response, so your
agent usually reads them to you verbatim. Here is what they mean and
what to do.

## Connection and authentication

**The client cannot connect at all.**
Check the URL character for character:

```
https://kafkai.com/mcp
```

The path ends in `/server`. The client must support the MCP
streamable HTTP transport — stdio-only clients cannot reach a remote
server.

**The sign-in page never appears (OAuth clients).**
Pop-up blockers are the usual cause. Allow the pop-up, or remove and
re-add the connector to restart the flow.

**Calls fail with an authorization error after working before.**
For OAuth clients: remove and re-add the connector to sign in again.
For API tokens: the token was probably revoked — check the
[API tokens page](https://kafkai.com/en/accounts/api-tokens/) and issue a new one if
needed. Tokens are shown only once, so a lost token is replaced, not
recovered.

**"No Kafkai user found."**
The account you authenticated with does not exist on kafkai.com.
[Register](https://kafkai.com/en/register/) first, then reconnect.

## Credits

**"No credit wallet found" or "Insufficient credits."**
Your balance cannot cover the call. Check it (free) by asking the
agent for your credit balance, then top up on the
[pricing page](https://kafkai.com/en/pricing/). Calls refused for balance reasons cost
nothing.

## Projects and data

**"Project '…' not found."**
The project id is wrong or the project belongs to a different account.
Ask the agent to list your Kafkai projects and use an id from that list.

**Keyword tools return empty lists on a new project.**
Research runs in the background and takes a few minutes after
project creation. Ask for the project summary — while counts are
still zero, the research has not finished. If a project stays empty
for hours, [contact support](https://kafkai.com/en/contact/).

**"Competitor '…' not found in this project."**
Ask the agent to list the project's competitors and use a domain from
that list — the value must match the tracked domain, not an arbitrary
URL.

**The update was not queued.**
Only one ranking update per project runs at a time. Wait for the
current one to finish; the keyword tools always serve the freshest
completed data in the meantime.

**`kafkai_publish_article` returns "Publishing failed".**
The destination refused the post, and the error carries its reason.
Check the destination's URL and credentials with
`kafkai_list_publishing_destinations`, fix the destination, then ask
the agent to publish again. For a WordPress destination, the usual
cause is a user without write permission. For more information, see
[Connect WordPress](https://kafkai.com/en/docs/wordpress/#if-the-test-passes-but-publishing-fails).

## Somewhere else entirely

If none of this matches what you see,
[contact support](https://kafkai.com/en/contact/) and include the tool name and the
error text from the response. The `_usage` and error objects in tool
responses carry no secrets, so they are safe to paste.
