# A little bird says what to try next.

What a refusal from the connection means, and what to do about it.

Every tool error carries a message, a next step, and whether it can be retried. Reconnecting does not change access, monitoring or allowance. When a change or a check may have started, read back before you ask again.

## Pick what you saw

| What you saw | Error codes | What it means | What to do |
| --- | --- | --- | --- |
| It says I have no sites. | `list_sites` returns `entryKind` `no_access` or `pending_setup` | Your account has no site access yet, or setup is not finished. An empty list does not mean the account is ready. | Ask your assistant for the `entryPath` that `list_sites` returned, and open it. For a new account, that path leads to setup, to pricing, or to an invitation from your team. If you expected a site, check that you signed in with the intended Dr. Canary account. |
| It asked me to sign in again. | `unauthenticated`, `invalid_token` | The connection could not be authenticated, or is no longer authorized. Your app may renew an ordinary expired sign-in on its own. Give it that chance before you reconnect. | Let your app renew the connection first. Reconnect only if renewal cannot recover it, from your app’s connection settings. In Codex, `codex mcp login dr-canary` opens sign-in again. In Claude Code, run `/mcp` and select dr-canary. |
| It refused a change. | `owner_or_admin_only`, `not_a_member`, `no_monitoring`, `quota_exhausted` | Your role, your membership, the site’s monitoring or its allowance does not allow it. Reconnecting will not grant it. | Read the error’s next step. It names the action that would allow it. Ask an owner or admin to save a shopper change, or review monitoring for the site in Dr. Canary. Review the site’s allowance in Dr. Canary before requesting another check. |
| The check did not start, or I cannot tell. | `outcome: unknown`, `unavailable`, `inspection_in_flight` | A check may have started even though the answer was lost. That is an unknown outcome, not a failure. | Read the site’s recorded checks with `list_runs` before asking again. For a Group, read the same Group with `get_group`. For a finding, read the finding’s thread in Dr. Canary. Asking twice can start two checks and use allowance twice. If it says `inspection_in_flight`, a check is already in progress. Follow that one. |
| The report came back as a link only. | `result_too_large` | The report is too large to return through the connection. It is not an empty report. | Open the link in Dr. Canary to read the report. Your assistant has not read the report’s body, so it cannot summarise what is in it. |
| It says too many requests. | `rate_limited` | Either your account made 60 tool calls in a rolling minute on one server instance, or that instance was already serving as many signed-in people as it holds at once. | Wait for the seconds given in `retryAfterSeconds`. Then continue. This limit is not your check allowance. |
| It tested the wrong thing. | No error code | The basic check uses the first saved shopper that has not been retired, including a paused one. A check request names a site, not a shopper, a journey or a web address. | Ask your assistant to list your saved shoppers with `list_assignments`. A shopper you just created or edited is not necessarily the one that runs. Retire a shopper you no longer want, so it stops its future checks. |

## Reading an error

A refused tool call comes back marked as an error, with JSON that carries these fields:

| Field | What it carries |
| --- | --- |
| `code` | The refusal, such as `no_monitoring`. |
| `message` | What happened, in one sentence. |
| `nextStep` | What to do about it. |
| `retryable` | Whether the same call can be tried again. |
| `outcome` | On a change or a check: `not_started` or `unknown`. |
| `retryAfterSeconds` | On `rate_limited`: how long to wait. |

An input refusal such as `invalid_input`, `invalid_focus` or `departments_required` means the request needs correcting. Nothing was changed.

## Renewing, then reconnecting

1. **Let the app renew** Your app may renew an ordinary expired sign-in on its own. Give it that chance before you reconnect.

2. **Reconnect only if renewal fails** In ChatGPT, open Settings › Plugins › Dr. Canary and choose Reconnect. In Claude Code, run `/mcp`, select dr-canary, and authenticate. In Codex, run this command.

   ```
   codex mcp login dr-canary
   ```

3. **Know what it cannot fix** Reconnecting does not grant access, a role, monitoring or allowance the account does not have.

## A change with an unknown outcome

The rule that matters most: read back before you repeat. A change or a check whose answer was lost may still have happened.

- After a check request: read the site’s recorded checks with `list_runs`. For a Group, read `get_group` for the same Group. For a finding, read its thread in Dr. Canary.
- After a shopper save, a calendar change or a retirement: read the saved shoppers with `list_assignments`.
- A missing row does not prove the change failed, and does not make a repeat safe.
- Retry a change only when the error says `outcome: not_started` and `retryable: true`, after its next step.

## Slow or pending is not failed

- A check request comes back `queued` or `running`. That means it was admitted, not that it finished.
- A report can be `assembling`, which means it is being put together. It is not published yet.
- A finished check is not a published report.
- A check’s status is not a verdict about your website.

## When to open Dr. Canary instead

- A report too large to return: open the link it came back with.
- An allowance or monitoring question: review the site in Dr. Canary.
- A finding recheck you cannot confirm: read the finding’s thread.
- `unavailable` or `integration_unavailable` that keeps coming back: try again later. If it continues, contact support at tom@drcanary.com.

## What it does not do

- Reconnecting does not grant access, monitoring or allowance.
- A check request names a site, not a shopper, a journey or a web address.
- A missing record does not confirm that a change failed or that a repeat is safe.
- A queued check is not a finished check, and a finished check is not a published report.

## Ask your assistant

- “Did my last check request go through? Read the recorded checks before asking again.” Uses `list_runs`.
- “Why was my shopper change refused?” Uses `list_assignments`.
- “Which Dr. Canary sites can you see, and is setup finished?” Uses `list_sites`.

More examples: https://www.drcanary.com/mcp/examples/

## Questions

### Why does my assistant say I have no sites?

Your account has no site access yet, or setup is not finished. `list_sites` returns an `entryPath` that leads to the next step. Open it in Dr. Canary.

### Will reconnecting fix a refused change?

No. A refusal about your role, monitoring or allowance stays until that changes. Reconnect only when the app cannot renew an expired sign-in.

### The answer was lost after I asked for a check. Should I ask again?

Not yet. Read the site’s recorded checks first, because asking twice can start two checks and use allowance twice. Retry only when the error says `outcome: not_started` and `retryable: true`.

### Why did I only get a link to the report?

The report was too large to return through the connection. It is not empty. Open the link in Dr. Canary to read it.

### What does too many requests mean?

Either your account made 60 tool calls in a rolling minute on one server instance, or that instance was already serving as many signed-in people as it holds at once. Wait the seconds in `retryAfterSeconds`, then continue. It is not your check allowance.

### Why did it test a different shopper than the one I just edited?

The basic check uses the first saved shopper that has not been retired, including a paused one. It is not necessarily the one you just created or edited. There is no way to pick another.

### Who do I contact if it keeps failing?

If `unavailable` keeps coming back after you try again later, contact support at tom@drcanary.com.

## Related

- [Connect](https://www.drcanary.com/mcp/) · [markdown](https://www.drcanary.com/mcp.md)
- [Permissions](https://www.drcanary.com/mcp/permissions/) · [markdown](https://www.drcanary.com/mcp/permissions.md)
- [Tools](https://www.drcanary.com/mcp/tools/) · [markdown](https://www.drcanary.com/mcp/tools.md)
- [Examples](https://www.drcanary.com/mcp/examples/) · [markdown](https://www.drcanary.com/mcp/examples.md)

https://www.drcanary.com/mcp/troubleshooting/ · updated 2026-11-11