---
title: "Troubleshooting"
section: "Autonomous Agents"
description: "Fixes for SmartestQA autonomous agents: install blocked, settings that will not save, Run now greyed out, budget blocked, stopped at limit, denied tools, proposals, reports."
url: https://docs.smartestqa.ai/en/ai-agents-troubleshooting.html
audience: [customer, admin]
updated: 2026-11-08
keywords: "agent error install disabled repository smoke pipeline budget blocked stopped at limit denied apply failed approved overdue claude desktop report not delivered webhook run failed"
---
# Autonomous Agents: 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**

1. Search this page ( Ctrl + F ) for a word of the message.
2. Open the entry and work through Check .
3. Apply Fix , then run the agent once with Run now .
4. Still stuck: write to info@smartestqa.ai with the run number.

## Page and install

### Problem: “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**](https://docs.smartestqa.ai/en/ai-agents-catalog.html#install) is greyed out too.
- **Fix:** Pick the project in the project selector in the header. The page reloads its agents.

### Problem: “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](https://docs.smartestqa.ai/en/company-settings-users.html#project-access).

### Problem: The Install button of an agent is greyed out _(Install)_

- **Why:** The agent needs something the project does not have yet. The amber box on the card says what: a [code repository](https://docs.smartestqa.ai/en/deployments-repos.html#add-repo), a [repository token](https://docs.smartestqa.ai/en/deployments-repos.html#token-types) that works, or a [Smoke pipeline](https://docs.smartestqa.ai/en/schedule-create.html#tags).
- **Check:** The messages are listed in [When Install is not possible](https://docs.smartestqa.ai/en/ai-agents-catalog.html#blocked).
- **Fix:** Use [**Connect a repo**](https://docs.smartestqa.ai/en/ai-agents-catalog.html#blocked) or [**Open Deploys & Repos**](https://docs.smartestqa.ai/en/ai-agents-catalog.html#blocked) on the card. For **Deploy verification**, also create a pipeline tagged `smoke` in **[Schedule](https://docs.smartestqa.ai/en/schedule-create.html#create)**. Reopen the [catalog](https://docs.smartestqa.ai/en/ai-agents-catalog.html#install) afterwards.

### Problem: An agent shows Installed, but I can’t find it _(Install)_

- **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](https://docs.smartestqa.ai/en/ai-agents-catalog.html#pause-delete); the catalog then offers it again.

## Settings

### Problem: “Write what the agent should do (Instructions, box 1).” _(Settings)_

- **Why:** The instructions are empty, or box 1 [**What should the agent do?**](https://docs.smartestqa.ai/en/ai-agents-settings.html#easy-mode) is empty.
- **Fix:** The dialog switches to **Instructions**. Write the goal in box 1 or use [**Start from an example**](https://docs.smartestqa.ai/en/ai-agents-settings.html#easy-mode). See [The five boxes](https://docs.smartestqa.ai/en/ai-agents-settings.html#easy-mode).

### Problem: “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](https://docs.smartestqa.ai/en/deployments-repos.html#add-repo)**, or pick one or more in **Repos**. See [After each deploy](https://docs.smartestqa.ai/en/ai-agents-settings.html#deploy-trigger).

### Problem: Install or Save shows an error in a red box _(Settings)_

- **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](https://docs.smartestqa.ai/en/ai-agents-settings.html#cron). |
  | the time zone | Pick one from the list or leave it empty. |
  | the [late cutoff](https://docs.smartestqa.ai/en/ai-agents-settings.html#claude-task) | Write it as HH:mm, for example `08:00`. |
  | [e-mail addresses](https://docs.smartestqa.ai/en/ai-agents-settings.html#reports) | Valid addresses, comma separated, at most 10. |
  | the webhook address | Start with `http://` or `https://`; not SmartestQA itself or a local address. |
  | [max steps, cost or budget](https://docs.smartestqa.ai/en/ai-agents-settings.html#limits) | 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](https://docs.smartestqa.ai/en/ai-agents-catalog.html#daily)** for red runs. |
  | tools that run only on the server | Set [**Runs on**](https://docs.smartestqa.ai/en/ai-agents-settings.html#runs-on) to [**Smartest server (project LLM API)**](https://docs.smartestqa.ai/en/ai-agents-settings.html#runs-on). |
  | a repository or the Smoke pipeline | See [Install greyed out](https://docs.smartestqa.ai/en/ai-agents-troubleshooting.html#fix-install-disabled). |
- **Fix:** Correct the field and save again. Nothing is saved while the red box is shown.

### Problem: 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](https://docs.smartestqa.ai/en/ai-agents-settings.html#easy-mode)** (or from the text in Advanced), then untick it.

### Problem: “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**](https://docs.smartestqa.ai/en/ai-agents-settings.html#runs-on) on the server. The Claude Desktop option is greyed out for this agent.

### Problem: “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](https://docs.smartestqa.ai/en/ai-agents-catalog.html#custom).

## Runs

### Problem: Run now is greyed out _(Runs)_

- **Why:** The agent is paused, or it already has a run going (the button says [**Running now**](https://docs.smartestqa.ai/en/ai-agents-runs.html#run-now)). An agent has at most one run at a time.
- **Fix:** [Switch the agent on](https://docs.smartestqa.ai/en/ai-agents-catalog.html#pause-delete), or wait for the current run to end. A run with no progress is closed after 10 minutes; see [stuck runs](https://docs.smartestqa.ai/en/ai-agents-numbers.html#stale).

### Problem: A run shows Budget blocked _(Runs)_

- **Why:** The agent’s spend today reached its **Daily budget**, before or during the run.
- **Check:** The card’s **[Today](https://docs.smartestqa.ai/en/ai-agents-numbers.html#budget-meter)** meter and the costs on **[Runs](https://docs.smartestqa.ai/en/ai-agents-runs.html#runs-tab)**. “Today” starts at midnight in the agent’s [time zone](https://docs.smartestqa.ai/en/ai-agents-settings.html#cron). See [When a run stops](https://docs.smartestqa.ai/en/ai-agents-numbers.html#limits).
- **Fix:** Wait for the next day, or raise [**Daily budget (USD)**](https://docs.smartestqa.ai/en/ai-agents-settings.html#limits) in [Limits](https://docs.smartestqa.ai/en/ai-agents-settings.html#limits) (up to 100). If one run costs much more than usual, look at [its steps](https://docs.smartestqa.ai/en/ai-agents-runs.html#run-detail) first.

### Problem: A run shows Stopped at limit _(Runs)_

- **Why:** It used all **[Max steps per run](https://docs.smartestqa.ai/en/ai-agents-settings.html#limits)**, 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](https://docs.smartestqa.ai/en/ai-agents-runs.html#run-detail): is the agent repeating the same call or reading too much?
- **Fix:** Narrow the job ([box 2](https://docs.smartestqa.ai/en/ai-agents-settings.html#easy-mode) [**What should it look at?**](https://docs.smartestqa.ai/en/ai-agents-settings.html#easy-mode), or **At most this many items per run:**), then raise the limit if the job really needs more.

### Problem: A step says DENIED _(Runs)_

- **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](https://docs.smartestqa.ai/en/ai-agents-settings.html#tools)**, 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](https://docs.smartestqa.ai/en/company-settings-roles.html) 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**](https://docs.smartestqa.ai/en/ai-agents-runs.html#run-now).

### Problem: A run shows Failed, or stays Running for a long time _(Runs)_

- **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](https://docs.smartestqa.ai/en/ai-agents-runs.html#run-detail) and the last **ERROR** step.
- **Fix:** For an AI connection problem, ask your admin to check the project’s [AI settings](https://docs.smartestqa.ai/en/project-settings-ai.html#ai-account). For a full queue, try again later. Otherwise run it again with [**Run now**](https://docs.smartestqa.ai/en/ai-agents-runs.html#run-now); if it fails the same way, write to info@smartestqa.ai with the run number.

### Problem: A scheduled or deploy agent did not run _(Runs)_

- **Check:** 1. The agent is switched on (runs that come due while paused are skipped, not caught up).
  2. The **Next** time on the [card](https://docs.smartestqa.ai/en/ai-agents-runs.html#card), in the agent’s time zone.
  3. For **After each deploy**: did a [new deploy](https://docs.smartestqa.ai/en/deployments-overview.html#history) 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.
  4. For Claude Desktop: see [the next entry](https://docs.smartestqa.ai/en/ai-agents-troubleshooting.html#fix-overdue).
- **Fix:** Correct the trigger in [Trigger](https://docs.smartestqa.ai/en/ai-agents-settings.html#trigger), or start it with [**Run now**](https://docs.smartestqa.ai/en/ai-agents-runs.html#run-now).

### Problem: “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](https://docs.smartestqa.ai/en/ai-agents-numbers.html#overdue).
- **Check:** 1. The computer was on and Claude Desktop was open at that time.
  2. The scheduled task exists in Claude Desktop with the text from [**Claude scheduled task prompt**](https://docs.smartestqa.ai/en/ai-agents-settings.html#claude-task).
  3. The [SmartestQA MCP](https://docs.smartestqa.ai/en/mcp-connect.html#claude-desktop) works in Claude Desktop (ask “Which SmartestQA projects can I access?”).
- **Fix:** Recreate the task from [the steps](https://docs.smartestqa.ai/en/ai-agents-settings.html#claude-task), or set [**Runs on**](https://docs.smartestqa.ai/en/ai-agents-settings.html#runs-on) to the server so it runs when your computer is off.

## Proposals

### Problem: “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](https://docs.smartestqa.ai/en/company-settings-roles.html#matrix), or the arguments were cut when they were saved.
- **Check:** [Open the step](https://docs.smartestqa.ai/en/ai-agents-runs.html#run-detail): 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.

### Problem: A proposal stays APPROVED _(Proposals)_

- **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](https://docs.smartestqa.ai/en/ai-agents-runs.html#proposals).

### Problem: Proposals to review shows a number, but nothing is waiting _(Proposals)_

- **Why:** The card counts all proposals recorded by today’s runs, also those already applied or dismissed. See [the formula](https://docs.smartestqa.ai/en/ai-agents-numbers.html#kpis).
- **Fix:** Nothing to fix. Open [today’s runs](https://docs.smartestqa.ai/en/ai-agents-runs.html#runs-tab) to see which proposals still have **Apply** buttons.

## Reports

### Problem: “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](https://docs.smartestqa.ai/en/ai-agents-settings.html#reports). Reports are still readable in the [run detail](https://docs.smartestqa.ai/en/ai-agents-runs.html#run-detail) and as PDF.

### Problem: Slack, Teams, Discord or WhatsApp can’t be ticked _(Reports)_

- **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](https://docs.smartestqa.ai/en/integrations-notifications.html)** in a new tab. Come back and reopen the settings.

### Problem: Send a test says Failed for a target _(Reports)_

- **Check:** 1. Webhook: the address answers with a 2xx status to a JSON POST from the internet.
  2. Channel: its webhook in **[Integrations](https://docs.smartestqa.ai/en/integrations-notifications.html)** is still valid.
  3. E-mail: the address is spelled right; check the spam folder.
- **Fix:** Correct the target and click [**Send a test**](https://docs.smartestqa.ai/en/ai-agents-settings.html#reports) again. The test uses the screen’s values and saves nothing, so save afterwards.
