- Docs
- AI
- MCP & AI assistants
- Troubleshooting
Troubleshooting
Find the message or symptom you or your assistant see. Each entry says why it happens, what to check and how to fix it.
In short
On this page you can
- Fix a connection that does not show up in Claude, Claude Code or Cursor.
- Fix sign-in problems with the claude.ai connector.
- Understand refusals the assistant reports, such as STALE_PREVIEW or READ_ONLY.
- Unblock a scenario that is BLOCKED after three red runs.
How to use it
- Find the message the client or the assistant shows.
- Open the entry and work through Check.
- Apply Fix, restart the client if the entry says so.
- Ask “Which SmartestQA projects can I access?” to test again.
Connecting#
SmartestQA does not appear in Claude (or its tools are missing)Connect
- Why
- The client did not reload, the extension is off, or the server could not start.
- Check
-
- Claude Desktop: you quit it completely, including the tray icon, and opened it again. Settings › Extensions shows SmartestQA switched on.
- claude.ai: SmartestQA is enabled in the chat’s tools menu.
- Claude Code:
claude mcp listshows it; start a new session. Cursor: Settings › MCP. - The client’s MCP log names a missing setting when the server did not start: macOS
~/Library/Logs/Claude/mcp-server-*.log, Windows%APPDATA%\Claude\logs\.
- Fix
- Restart the client. If it still fails, install again from the MCP tab.
“Select a host to see the command with your API key.”Connect
- Why
- The command needs a host’s API key, and no host with a key is selected.
- Fix
- In Device FarmTest Agents, click your host under Localhost (named after your email), then open the MCP tab.
The install command stops: Node.js is missing or too oldConnect
- Why
- The one-line install and the zip run on Node.js: “Needs Node.js 18 or newer on the machine.”
- Fix
- Install a current Node.js from nodejs.org, open a new terminal and run the command again. Claude Desktop users can use the .mcpb extension instead, which needs no Node.js.
“No MCP client was found on this machine (Claude Desktop, Claude Code or Cursor).”Connect
- Why
- The installer registers SmartestQA in the configuration of the clients it finds, and found none.
- Fix
- Open Claude Desktop once, or run Claude Code once (
claude), then run the command again. For Cursor, add--client=cursorto the manual command. For another client, see Another MCP client.
macOS or Linux: ./smartest-mcp says “Permission denied”Connect
- Why
- The unpacked file lost its permission to run (some unzip tools and copies drop it).
- Fix
- Start it with
sh ./smartest-mcp …, exactly as the manual command on the MCP tab does.
Claude Desktop shows a security warning when installingConnect
- Why
- “Claude shows a security warning during installation. This is normal for every local extension.”
- Fix
- Continue the installation if the file came from the MCP tab of your SmartestQA.
I changed the key but the old one is still usedConnect
- Why
- “After changing the key, quit Claude and open it again — the running server keeps the old one.”
- Fix
- Quit the client completely and open it again.
Connector sign-in (claude.ai)#
“This account has no password yet. Set one with the link in your email, then try again.”Sign-in
- Why
- The connector signs you in with email and password, and your account has none yet (for example you were invited and never set one).
- Fix
- Set your password with the link in your invitation e-mail (see Quick Start), then connect again.
“Wrong email or password.” / “Too many failed attempts. Please try again in 15 minutes.”Sign-in
- Why
- The sign-in did not match. After 10 failures within 15 minutes, sign-in from that address is paused for 15 minutes.
- Fix
- Check the address you sign in to SmartestQA with. Reset the password with Forgot Password? on the SmartestQA sign-in page if needed, then wait out the pause.
“This connection request is not valid or has expired. Go back to Claude and start connecting again.”Sign-in
- Why
- The sign-in window was opened from an old or incomplete link, or waited too long.
- Fix
- Close the window, go back to Claude and click connect again.
“Could not save your decision. Please try again.”Sign-in
- Why
- Your Allow or Deny could not be sent: the connection dropped or your SmartestQA session expired.
- Fix
- Click again. If it repeats, sign in to SmartestQA in the same browser and start connecting again from Claude.
Claude says the SmartestQA connection was rejected or expiredSign-in
- Why
- The renewal token was not used for 30 days, was revoked, or your access changed.
- Fix
- In Claude, Settings › Connectors: disconnect SmartestQA and connect it again.
Using the tools#
The assistant says the SmartestQA key was rejected (401)Access
- Why
- The key is wrong, its host was deleted, or the key belongs to another SmartestQA environment than the package.
- Check
- Your host still exists in Test Agents, and you installed the package from the same SmartestQA you copied the key from.
- Fix
- Copy the key again with Copy API Key, paste it in the extension settings (or run the install command again) and restart the client.
“not allowed for this account (403)” or ACCESS DENIEDAccess
- Why
- The key works, but your user may not do this, or may not open this project. The message from SmartestQA says what.
- Fix
- Ask an Admin for access to the project. For an action your role cannot do, ask an Admin to do it: roles are fixed, so an Admin cannot add a single permission to your role. Do not renew the key: it is fine.
The assistant cannot reach the SmartestQA server, or it times outNetwork
- Fix
- Check the internet or VPN connection of the machine the MCP runs on, and that a company proxy allows SmartestQA. Then ask again.
The assistant works on the wrong projectUse
- Fix
- Name the project in each request: “In project Web Shop, …”. The assistant may not guess a project; if it did not ask, tell it which one.
“this connection to … is read-only”Use
- Why
- This install was set up read-only (
SMARTEST_READONLY=true): only reading tools are offered. - Fix
- Use a normal install for writing, or make the change in SmartestQA. See Read-only connection.
The assistant reports STALE_PREVIEWChanges
- Why
- The preview was already applied, the records changed since it was made, it is older than 30 minutes, or the MCP restarted. Nothing was written.
- Fix
- Let the assistant propose again and read the new diff. See Previews.
“NOT DONE - the user declined the confirmation dialog.” / “NOT DONE - this action needs the user's click…”Changes
- Why
- The action needs your click in a dialog: you declined, or your client cannot show dialogs. Nothing was changed.
- Fix
- If you meant to do it, ask again and confirm. If the client shows no dialogs, do it in SmartestQA. See Actions that need your click.
“only an admin can remove records (your role: …); nothing was removed”Changes
- Fix
- Ask an Admin to approve and confirm the removal, or archive the records in SmartestQA if your role allows it.
A scenario is BLOCKEDScenarios
- Why
- Its dry run was not green three times. The assistant stops so it does not keep changing steps blindly.
- Fix
- Decide with the assistant (see The scenario flow): you fixed the cause (app, data, environment), the proof it checks must change, or the scenario must be split. It runs again only after you confirm “Run it again?”.
A dry run on my agent does not startScenarios
- Fix
- The agent must be online in Test Agents. See the agent fix, or ask for the dry run on the server.
The assistant reports UNKNOWN_TOOL or RULES_OUTDATEDUse
- Why
- UNKNOWN_TOOL: the assistant used a tool name the server does not have, often from an older conversation. RULES_OUTDATED: the step rules changed; the assistant must read them again. Nothing was written.
- Fix
- Let the assistant continue; it re-reads the tool list or the rules. If it keeps happening, update the MCP (
smartest-mcp --update, or a new .mcpb) and start a new chat.
A write is refused because of the languageUse
- Why
- Content is written in the project’s language. The assistant tried another one, or the project has none set.
- Fix
- Tell the assistant the project’s language (it can save it if none is set). You can keep chatting in your own language.
Still stuck: write to info@smartestqa.ai with the client you use, the time and the message.
Didn’t find your answer?Write to support with your project name and what you see on screen.
info@smartestqa.ai