MCP server problems

Start with doctorCopy Anchor Link

npx -y @debugai/mcp doctor

It prints four sections:

It ends with ✓ Everything checks out. or the number of problems to fix. To see which key is in use and whose account it is, run:

npx -y @debugai/mcp status

Each heading below is a message as DebugAI prints it. <Client> stands for a client's name, such as Cursor.

What doctor saysCopy Anchor Link

Node N is too oldCopy Anchor Link

The MCP server needs Node.js 18.14.1 or newer. Install a current Node.js LTS release, check it with node -v, and run npx -y @debugai/mcp setup again.

No API key foundCopy Anchor Link

You have not signed in on this machine. Run:

npx -y @debugai/mcp login

Key does not look like a DebugAI keyCopy Anchor Link

The key in use does not start with dbg_. If you set DEBUGAI_API_KEY in your environment, that value wins over the stored key, so check it first. Otherwise run npx -y @debugai/mcp login --force.

Config file is readable by other usersCopy Anchor Link

On macOS and Linux, the file that holds your key should be readable by you alone. Doctor prints the fix:

chmod 600 ~/.debugai/config.json

Could not authenticate against the APICopy Anchor Link

Either your key was rotated, or the API cannot be reached from this machine. For a rotated key, run npx -y @debugai/mcp login --force. For the network, see Could not reach the DebugAI API.

<Client> — installed but DebugAI is not in its configCopy Anchor Link

The client is on this machine but has no DebugAI entry. Doctor prints the command, for example:

npx -y @debugai/mcp install --client=cursor

<Client> — debugai configured for ONE directory onlyCopy Anchor Link

DebugAI works in one folder only. claude mcp add does this by default, because it adds a server for the current directory. To use DebugAI in every project, run:

npx -y @debugai/mcp install --client=claude-code

<Client> — runs "@debugai/mcp" without a versionCopy Anchor Link

Without a version, npx runs the first copy it finds, and an old global install wins over the newest release. npx -y @debugai/mcp install --client=<id> rewrites the entry with @debugai/mcp@latest.

<Client> — pinned to <version>; newer releases will not reach it until you change that.Copy Anchor Link

Only a note. The entry names one version on purpose, so updates do not reach it. Run install --client=<id> if you want @latest back.

<Client> — an API key is written in plain text in its configCopy Anchor Link

The DebugAI entry in that client's config carries DEBUGAI_API_KEY in an env block. It works, but that key outranks the one login stores, so after you rotate your key this client keeps failing. It is also a key in a file that gets committed and shared. Run npx -y @debugai/mcp login, then delete the env block from the debugai entry in the file doctor names.

VS Code (native MCP) — no entry here, which is right with the DebugAI extension installedCopy Anchor Link

Only a note. The DebugAI extension registers the server in VS Code itself, so no entry is needed. See VS Code agent mode.

None detected.Copy Anchor Link

Doctor found no MCP client on this machine. npx -y @debugai/mcp install --list shows every client DebugAI knows and where it looks for each.

What install saysCopy Anchor Link

install (and setup, which runs it) writes to the clients it finds. A client counts as found when its config file or its app folder exists. To write one that was not found, name it: --client=<id> writes the entry anyway. The ids are claude-code, claude-desktop, cursor, windsurf, zed, gemini-cli, cline and vscode.

Before changing a file, install copies it to a backup next to it, named <file>.debugai-backup-<time>.

No MCP clients detected on this machine.Copy Anchor Link

setup stops here, before doctor, and the run counts as failed. Two common reasons:

• You only use VS Code. Nothing is wrong. The DebugAI extension already registers the server for VS Code's agent mode, and setup leaves VS Code out on purpose. See VS Code agent mode.
• Your client has never been opened on this machine, so its folder does not exist yet. Open it once, or name it: npx -y @debugai/mcp install --client=<id>.

could not parse (...) — left untouchedCopy Anchor Link

The client's config file is not valid JSON, so DebugAI did not touch it: rewriting a file it cannot read is how people lose their settings. Fix the file, or paste in the snippet install printed under it. For most clients it is:

{
  "mcpServers": {
    "debugai": {
      "command": "npx",
      "args": ["-y", "@debugai/mcp@latest"]
    }
  }
}

Each client's page under Connect an agent has its exact shape, for example Zed.

This file had comments; JSON does not keep them, so they were droppedCopy Anchor Link

Your config file had comments, and the rewritten file does not. The backup install made still has them.

The old entry carried DEBUGAI_API_KEY in plain text; it was not copied.Copy Anchor Link

The entry DebugAI replaced had your key written into it. The new entry has none, and the server reads the key login stores instead. Run npx -y @debugai/mcp login if you have not.

Unknown clientCopy Anchor Link

The name after --client= is not one DebugAI knows. Run npx -y @debugai/mcp install --list for the names.

No API key stored yet — run npx -y @debugai/mcp login to finish.Copy Anchor Link

The entries are written, but nothing is signed in yet. Run npx -y @debugai/mcp login. Without it, the first tool call asks you to sign in from the chat (see below).

Signing in from the terminalCopy Anchor Link

Sign-in was declined in the browser.Copy Anchor Link

Someone pressed Not me on the confirmation page. Run npx -y @debugai/mcp login again.

The code expired.Copy Anchor Link

The code lasts 10 minutes. Run npx -y @debugai/mcp login again.

Could not start the sign-in linkCopy Anchor Link

DebugAI could not be reached to start a sign-in. Check the network (see Could not reach the DebugAI API). Or copy your key from the Settings tab of your dashboard and store it directly:

npx -y @debugai/mcp login --key dbg_your_key

Lost contact with DebugAI while waitingCopy Anchor Link

The connection dropped while the terminal waited for you to confirm. Nothing was stored. Run npx -y @debugai/mcp login again when you are back online.

Signed in, but the key could not be savedCopy Anchor Link

The folder for ~/.debugai/config.json is not writable. Make it writable, or set DEBUGAI_CONFIG_PATH to a file you can write, and run login again.

That does not look like a DebugAI key. They start with dbg_.Copy Anchor Link

The value after --key is not a DebugAI key. Copy it again from the dashboard.

A stored key exists but the API rejected it. Re-linking.Copy Anchor Link

Not a failure. Your stored key no longer works, so login starts a fresh sign-in. Confirm the code in the browser as usual.

npx.ps1 cannot be loaded because running scripts is disabled on this systemCopy Anchor Link

Windows PowerShell blocks the npx script on many machines. Run the command through npx.cmd, which is not blocked:

npx.cmd -y @debugai/mcp setup

Or allow signed scripts for your own user, which changes a PowerShell security setting:

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

What your agent passes onCopy Anchor Link

These come back from a tool call. Your agent should relay them. If it does not, ask it what the tool returned.

DebugAI is not connected to an account yet.Copy Anchor Link

The server has no key, so the tool call itself started a sign-in. The agent passes on an address and a code. Open the address, sign in, confirm the code, then ask the agent to call the tool again. The key is picked up on the next call, with no client restart. You can sign in from a terminal instead with npx -y @debugai/mcp login.

DebugAI authentication failed: the API key this server has was rejectedCopy Anchor Link

The stored key was rotated, revoked or mistyped. Run:

npx -y @debugai/mcp login --force

Then ask the agent to retry, with no restart needed. If it is refused again, run npx -y @debugai/mcp doctor: a key written into a client's config is still winning.

DebugAI authentication failed. API key invalid or expired.Copy Anchor Link

The same, from the server the VS Code extension runs for VS Code's agent mode. Run DebugAI: Sign In in VS Code.

DebugAI needs an API key to start the MCP server.Copy Anchor Link

VS Code tried to start the extension's MCP server before you signed in. Press Set API Key, or run DebugAI: Sign In.

DebugAI free tier daily quota reached (10 debugs/day).Copy Anchor Link

Today's 10 free debugs are used. The count resets at 00:00 UTC, and retrying before then is refused the same way. lookup_error still works and costs nothing. Pro lifts the daily cap; see Plans and limits.

DebugAI monthly usage ceiling reachedCopy Anchor Link

A paid account reached the separate limit that sits far above the plan's included debugs, there to stop runaway scripts. It resets on the 1st of the month (UTC). If the use is real, write to us from Messages on your dashboard.

DebugAI rate limit hit (transient).Copy Anchor Link

A short burst limit. Wait the number of seconds it names, then retry. No plan raises it.

Memory lookup rate limit reached. Call debug_error, or try again in a few minutes.Copy Anchor Link

lookup_error allows 300 lookups per 15 minutes for an account. An agent calling it in a loop reaches that. debug_error still works in the meantime.

DebugAI engine temporarily unavailable (HTTP 503)Copy Anchor Link

Something failed on DebugAI's side. The message may add what the service said, including that the attempt was not counted. Retry after a minute, and check status.debugai.io if it persists.

A debug_error call the server stops waiting for shows up the same way, as HTTP 504. It waits 150 seconds by default, set by DEBUGAI_TIMEOUT_MS.

Could not reach the DebugAI API atCopy Anchor Link

The request never reached DebugAI. You are offline, behind a proxy that blocks it, or DEBUGAI_API_BASE points somewhere wrong. Unless DebugAI told you to set DEBUGAI_API_BASE, remove it: the default is https://debugai-mvp-production.up.railway.app/api. The hosts to allow are listed under Behind a proxy or firewall.

DebugAI refused this callCopy Anchor Link

DebugAI turned down the arguments and says why after the colon. The same call is refused the same way, so the agent has to change what the reason names.

DebugAI did not recognise what this call referred to (HTTP 404).Copy Anchor Link

Almost always report_outcome with a debugLogId this account was never given. The agent should use the id from the debug_error answer in the same session. If every call is answered this way, DEBUGAI_API_BASE is probably wrong.

Memory lookup is not available on this DebugAI server yet.Copy Anchor Link

The server at DEBUGAI_API_BASE is older than lookup_error. Remove DEBUGAI_API_BASE to use DebugAI's own API.

No local files read: there is no usable project rootCopy Anchor Link

The server could not tell which project it is in, so it read no files and answered from the error text and your project index alone. That happens when the agent runs from your home folder, a folder above it, or the root of a drive. DebugAI never treats those as a project, and the same goes for these:

• The Windows profile seen from WSL: /mnt/c, /mnt/c/Users or /mnt/c/Users/<name>.
• A network share, such as \\server\share.
• A WSL distribution seen from Windows: \\wsl.localhost\<distro>, its /home, or /home/<name>.

Any folder inside those is fine. To fix it, start your agent in the project folder, or have it pass projectRoot with the project's absolute path. With the standalone server, an absolute filePath inside a git repository names that repository too.

Other problemsCopy Anchor Link

DebugAI does not show up in my clientCopy Anchor Link

Run npx -y @debugai/mcp doctor first. If it says the client is configured, the client has not loaded the entry yet:

The AI agents quickstart has the whole setup.

The Claude Code hook never says anythingCopy Anchor Link

The hook is meant to be quiet. It speaks only when your project's memory holds something for the failed command's output: a stored fix for that error, or advice that was reported as failed. It also stays silent when:

• The failure is not from a Bash or PowerShell command, or the command was interrupted.
• The output is shorter than 12 characters.
• No key is stored. The hook never starts a sign-in, so run npx -y @debugai/mcp login once.
• The memory lookup takes longer than 8 seconds.

Run /hooks in Claude Code to check the hook is registered. Setup is on the Claude Code page.

The extension and the MCP server remember different things for one projectCopy Anchor Link

On Windows this is a known gap. The extension and the standalone MCP server spell the same folder differently (c:\Users\me\repo and C:/Users/me/repo), so they compute two different project ids. They keep two separate memories of one checkout, and the MCP server does not see the index the extension built. On macOS and Linux they match when the folder you open in the editor is the root of the git repository. More in Error memory.