Help: Troubleshooting
Troubleshooting
Find the line that matches what you see. Each entry gives the cause and the fix.
The agent does not connect
| What you see | Cause | Fix |
|---|---|---|
| The client reports HTTP 401, "authentication required" or "needs authentication" when it connects to the MCP server | The request carried no agent key, or the key is wrong or revoked. The MCP server refuses every request without a valid key. | In the client's configuration, set the header "Authorization" to the word Bearer, a space and the agent's key, as shown in Connect an agent. If you no longer have the key, see "The key is rejected" below. |
| Claude says the connector could not connect, or asks you to sign in | The connector was added without the "authorization" request header, or the value does not start with the word Bearer and a space before the key. | A connector's headers cannot be edited. Remove the connector and add it again as described in Connect an agent, with "No sign in" under "Authentication". |
| The dialog for a custom connector in Claude has no "Request headers" section | Anthropic has switched that section on for some accounts only. Without it the connector cannot send the key. | In the Claude desktop app, use the bridge described in Connect an agent. On claude.ai there is no alternative until the section appears. |
| The client cannot reach the MCP server at all | The address in the client's configuration is wrong. | Use the address from Connect an agent exactly: the address of the site followed by /mcp. Check that the site opens in a browser from the same machine. |
| A tool error starting "Could not reach funwatcher at" | The MCP server could not reach the funwatcher API. | Only the operator of the deployment can fix this. See Get help. |
| The agent runs but nothing appears in the Inbox | The agent is not calling the tool, the outcome was not "require approval", or you are looking at another account. | Open the agent's page under Agents and read "Last used" next to its key. "never" means no call has arrived. If calls arrive, look in the Ledger for a request.created event: an action that was auto allowed or prohibited never appears in the Inbox. |
The key is rejected
What you see. The agent reports HTTP 401 with "Invalid or revoked agent key." or "Missing or malformed Authorization header; expected Bearer <agent key>."
Cause. The key was mistyped or cut short, the key was revoked, the agent was revoked, or the key belongs to a different deployment.
Fix.
- Open the agent's page under Agents.
- Check "Status". If the agent is revoked, register a new agent.
- Compare the first characters of the key in the agent's configuration with the "Prefix" of a key whose status is "active".
- If none matches, or you no longer have the key, select "Rotate: create a new key" and put the new key into the agent's configuration. In the Claude apps, remove the connector and add it again with the new key.
A key cannot be shown again. See Rotate or revoke an agent key.
No notification arrives
| Cause | How to tell | Fix |
|---|---|---|
| The request did not need a decision. | Its status is held, auto allowed or prohibited. Only pending requests notify anyone. | None needed. Open the Inbox to see held actions. |
| You are not allowed to decide it. | Your role in the account is viewer and no delegation covers the action type. See Roles. | Ask an owner for a delegation or a different invite. |
| The channel is switched off. | On Notification settings, "Enabled" is not ticked for Email or Push. | Tick "Enabled" and select "Save". |
| Quiet hours are in force. | The current time in your "Time zone" is between "Quiet hours start" and "Quiet hours end". | The notification is sent when quiet hours end. Clear both times and select "Save" to switch quiet hours off. |
| Push was never enabled on this device. | "Push devices" on the settings page reads "No devices are subscribed to push." or does not list this device. | Open the Inbox on the device and select "Enable push notifications on this device". Allow notifications when the browser asks. |
| The browser blocks notifications. | The Inbox shows "Notifications are blocked for this site in your browser settings." | Allow notifications for the site in the browser's own settings, then reload the Inbox. |
| The deployment cannot send. | The settings page shows "Web push is not configured on this server", or no email ever arrives from this deployment. | Only the operator of the deployment can fix this. See Get help. |
A notification never contains the request itself, only the agent, the action type, the amount and a link.
A request expired before anyone decided
What you see. The request is in History with the status "expired" and the agent says it was told not to act.
Cause. Nobody approved or denied it before its deadline. Unless the agent asks for a different time, the deadline is 60 minutes after the request arrives.
Fix.
- Have the agent submit the action again. An expired request cannot be approved.
- Make sure the people who can decide are notified: see "No notification arrives" above.
- If the deadline is too short for you, the agent's builder can ask for a longer one, up to 24 hours. See API overview.
- If someone will be away, an owner can create a delegation. See Delegations.
A rule does not match
What you see. A request got an outcome you did not expect. Its card names the rule that decided, or says "No rule matched; default requires approval."
| Cause | Fix |
|---|---|
| The rule is disabled or awaiting confirmation, so it is skipped. | On Policies, read the rule's "Status". Select "Enable", or "review" and then "Confirm and enable". |
| Another rule with a higher priority matched first. | The card's explanation names it. Move your rule above it with "Up", or narrow the other rule. See Reorder, enable and disable rules. |
| A prohibit rule matched. Prohibit wins whatever its priority. | Edit or disable the prohibit rule. Moving it does not help. |
| The amount condition did not apply: the request has no amount, or it is in another currency, or the rule's figure is not in minor units. | Open the request's page and compare. An amount condition compares cents with cents in the same currency. |
| The counterparty is not "new": an earlier request with the same counterparty was reported as executed. | None. This is how "new" is defined. Use a pattern condition if you need a different test. |
| The agent sent a different action type, reversible flag or payload field than the rule expects. | Open the request's page and read the card and the "Payload" against the rule's condition. See Build a rule with the form. |
| The agent has its own default outcome, which replaced a catch-all rule. The card's explanation starts with "Agent" and names it. | Open the agent's page under Agents and change "Default outcome". See Set a default policy for an agent. |
| The rule was changed after the request arrived. | None for that request. Rules apply once, on arrival. The next request uses the new rules. |
A limit is reached
| What you see | Cause | Fix |
|---|---|---|
| "Register an agent" shows a message that the plan allows a number of active agents and the account has that many | The account is at its plan's agent limit. | Revoke an agent you do not use, or pay for more agents. See When you hit a limit. |
| The agent reports HTTP 429 with "This agent already has" followed by a number of "requests awaiting a decision" | The agent has 25 requests that are pending or held. | Decide or cancel the waiting requests in the Inbox. |
| The agent reports HTTP 429 with "Rate limit exceeded." | More than 120 calls in 60 seconds with one key. | The agent should wait for the time in the answer and call less often. |
| A page says to try again later after several wrong passwords or codes | Too many attempts in a short time from your address or for your login. | Wait for the time the page states, then try again. |
The maintenance page
What you see. Every page, including these help pages, shows "funwatcher is under maintenance" with the message "This service is down for maintenance. Please try again in a few minutes.". Agents receive HTTP 503.
Cause. The operator of the deployment switched maintenance mode on.
Fix. Wait and reload. Nothing was lost: requests that already exist keep their status, and agents that submit during maintenance are told to retry later. Agents must not act on a request they could not submit. The login pages stay available so that an administrator can switch maintenance off.
Still stuck
See Get help.
Previous: Handling responses
Next: Get help
All help pages
Inbox
- Read a request
- Approve, deny or edit a request
- Held actions
- Expired requests and history
- Request statuses
Rules
- How rules work
- The default rules
- Write a rule in plain English
- Build a rule with the form
- Reorder, enable and disable rules
- Suggested rules
- Set a default policy for an agent
- Export your rules
Teams
Ledger
- What the ledger is
- Browse and filter the ledger
- Export and verify the ledger
- Payload retention
- Monthly statements
Billing
Account and security
- Change your password
- Two-factor authentication and recovery codes
- Rotate or revoke an agent key
- How your data is protected
- Closing an account