- Docs
- AI
- Autonomous Agents
- Troubleshooting
Troubleshooting
Find the message or symptom you see. Each entry says why it happens, what to check and how to fix it.
In short
On this page you can
- Find the exact message shown on the agent page, card, settings or run.
- Learn why it happens and what to check first.
- Apply the fix, with a link to the step that explains it.
How to use it
- Search this page (Ctrl+F) for a word of the message.
- Open the entry and work through Check.
- Apply Fix, then run the agent once with Run now.
- Still stuck: write to info@smartestqa.ai with the run number.
Page and install#
“Select a project from the header to manage its agents.”Page
- Why
- Agents belong to a project, and no project is selected. Install new agent is greyed out too.
- Fix
- Pick the project in the project selector in the header. The page reloads its agents.
“Could not load agents.”Page
- Why
- The agent list or runs could not be read: the connection dropped, your session expired, or you have no access to the selected project.
- Fix
- Click Retry. If it repeats, sign in again and check that you are a member of the project.
The Install button of an agent is greyed outInstall
- Why
- The agent needs something the project does not have yet. The amber box on the card says what: a code repository, a repository token that works, or a Smoke pipeline.
- Check
- The messages are listed in When Install is not possible.
- Fix
- Use Connect a repo or Open Deploys & Repos on the card. For Deploy verification, also create a pipeline tagged
smokein Schedule. Reopen the catalog afterwards.
An agent shows Installed, but I can’t find itInstall
- Why
- It is installed in the current project. Paused agents look dim, and the card may be further down the grid.
- Fix
- Check the project in the header and scroll the Agents tab. To start over, delete the agent; the catalog then offers it again.
Settings#
“Write what the agent should do (Instructions, box 1).”Settings
- Why
- The instructions are empty, or box 1 What should the agent do? is empty.
- Fix
- The dialog switches to Instructions. Write the goal in box 1 or use Start from an example. See The five boxes.
“Connect a code repo under Deploys & Repos first.” / “Choose which repos to listen to.”Settings
- Why
- The trigger is After each deploy. SmartestQA needs a repository to know about deploys, and with several repositories it needs to know which ones count.
- Fix
- Add a repository in Deploys & Repos, or pick one or more in Repos. See After each deploy.
Install or Save shows an error in a red boxSettings
- Why
- SmartestQA checks the settings again when you save and refuses values it cannot use.
- Check
The message is about Fix the name Name it, at most 150 characters; description at most 1,000. the cron expression Five fields, for example 0 6 * * *. See Schedule.the time zone Pick one from the list or leave it empty. the late cutoff Write it as HH:mm, for example 08:00.e-mail addresses Valid addresses, comma separated, at most 10. the webhook address Start with http://orhttps://; not SmartestQA itself or a local address.max steps, cost or budget Steps 1–60; cost above 0 and up to 10; budget above 0 and up to 100. “test fail” (On test failure) New agents cannot use this trigger. Use Daily triage for red runs. tools that run only on the server Set Runs on to Smartest server (project LLM API). a repository or the Smoke pipeline See Install greyed out. - Fix
- Correct the field and save again. Nothing is saved while the red box is shown.
I can’t untick a tool (it shows In instructions)Settings
- Why
- “Used in the instructions. Remove it from the instructions first to untick it.” An agent whose instructions call a tool it may not use would fail at that step.
- Fix
- Remove the tool name from the steps on Instructions (or from the text in Advanced), then untick it.
“This agent's tools run only on the SmartestQA server, so it cannot run in your LLM client.”Settings
- Why
- The agent uses only SmartestQA’s own tools (the report agents do). Claude Desktop cannot call them.
- Fix
- Leave Runs on on the server. The Claude Desktop option is greyed out for this agent.
“This text was written by hand; it can only be edited in Advanced mode.”Settings
- Why
- The instructions were not made with the five boxes (catalog agents, or text you edited by hand), so they cannot be split back into boxes.
- Fix
- Edit in Advanced. To use the boxes, start a Custom agent.
Runs#
Run now is greyed outRuns
- Why
- The agent is paused, or it already has a run going (the button says Running now). An agent has at most one run at a time.
- Fix
- Switch the agent on, or wait for the current run to end. A run with no progress is closed after 10 minutes; see stuck runs.
A run shows Budget blockedRuns
- Why
- The agent’s spend today reached its Daily budget, before or during the run.
- Check
- The card’s Today meter and the costs on Runs. “Today” starts at midnight in the agent’s time zone. See When a run stops.
- Fix
- Wait for the next day, or raise Daily budget (USD) in Limits (up to 100). If one run costs much more than usual, look at its steps first.
A run shows Stopped at limitRuns
- Why
- It used all Max steps per run, or its cost reached Max cost per run, before it gave a final answer.
- Check
- The error line of the run says which. Look at the steps: is the agent repeating the same call or reading too much?
- Fix
- Narrow the job (box 2 What should it look at?, or At most this many items per run:), then raise the limit if the job really needs more.
A step says DENIEDRuns
- Why
- Either the tool is not ticked for this agent, or the user the agent runs as lacks the permission the tool needs (the grey chip on Tools & autonomy, such as
VIEW_REPORT). A scheduled run runs as the agent’s creator; Run now as the person who clicked it. In a User role without permissions, agent tools are refused: “Agent tools are refused for this role today: its role has no permissions assigned.” - Fix
- Tick the tool. If the user lacks the permission, an Admin cannot add it: roles are fixed and cannot be edited. Admins have every permission, so let an Admin create the agent (its scheduled runs then run as that Admin) or start it with Run now.
A run shows Failed, or stays Running for a long timeRuns
- Why
- The model call or a tool failed, the project’s AI connection is not working, the run queue was full, or the run made no progress and was closed (Queued 15 minutes, Running 10 minutes, Claude Desktop 6 hours).
- Check
- The red line at the top of the run detail and the last ERROR step.
- Fix
- For an AI connection problem, ask your admin to check the project’s AI settings. For a full queue, try again later. Otherwise run it again with Run now; if it fails the same way, write to info@smartestqa.ai with the run number.
A scheduled or deploy agent did not runRuns
- Check
-
- The agent is switched on (runs that come due while paused are skipped, not caught up).
- The Next time on the card, in the agent’s time zone.
- For After each deploy: did a new deploy of the selected repository and environment arrive? “No new deploy, no run.” With All of them are deployed, every selected repository must have a new deploy.
- For Claude Desktop: see the next entry.
- Fix
- Correct the trigger in Trigger, or start it with Run now.
“Expected run did not arrive (…) — is Claude Desktop open?”Claude Desktop
- Why
- The agent runs in Claude Desktop, and 90 minutes after its scheduled time Claude Desktop has not asked for it. See the rule.
- Check
-
- The computer was on and Claude Desktop was open at that time.
- The scheduled task exists in Claude Desktop with the text from Claude scheduled task prompt.
- The SmartestQA MCP works in Claude Desktop (ask “Which SmartestQA projects can I access?”).
- Fix
- Recreate the task from the steps, or set Runs on to the server so it runs when your computer is off.
Proposals#
“The proposal could not be applied; see the step output for details.”Proposals
- Why
- The recorded call failed when it ran as you: the record changed or was removed since the run, you lack the permission, or the arguments were cut when they were saved.
- Check
- Open the step: its Output starts with the reason.
- Fix
- Fix the cause and click Apply again (the status APPLY_FAILED allows a retry), or make the change yourself in the screen and Dismiss the proposal.
A proposal stays APPROVEDProposals
- Why
- It came from a run in Claude Desktop, and SmartestQA could not apply it on its own. It waits for the agent’s next run in Claude Desktop.
- Fix
- Let the next scheduled run happen, or make the change by hand. See Proposal statuses.
Proposals to review shows a number, but nothing is waitingProposals
- Why
- The card counts all proposals recorded by today’s runs, also those already applied or dismissed. See the formula.
- Fix
- Nothing to fix. Open today’s runs to see which proposals still have Apply buttons.
Reports#
“No target selected: reports stay only in the run history.”Reports
- Why
- No channel is ticked, and no e-mail or webhook is filled in.
- Fix
- Add a target on Reports. Reports are still readable in the run detail and as PDF.
Slack, Teams, Discord or WhatsApp can’t be tickedReports
- Why
- The channel is not set up for the project (Set up in Integrations) or is switched off (Enable in Integrations).
- Fix
- Click the link next to it; it opens Integrations in a new tab. Come back and reopen the settings.
Send a test says Failed for a targetReports
- Check
-
- Webhook: the address answers with a 2xx status to a JSON POST from the internet.
- Channel: its webhook in Integrations is still valid.
- E-mail: the address is spelled right; check the spam folder.
- Fix
- Correct the target and click Send a test again. The test uses the screen’s values and saves nothing, so save afterwards.
Didn’t find your answer?Write to support with your project name and what you see on screen.
info@smartestqa.ai