# Troubleshooting

> Symptom, cause and fix for the problems people meet most — connecting, plan limits, access, timeouts, and keys on the wrong plane.

Kind: troubleshooting · ~3 min · Verified v0.237.0 · Next: [SDKs overview](https://pr-2197-stg.superartifacts.app/docs/sdks.md)

[Error codes](https://pr-2197-stg.superartifacts.app/docs/reference/errors.md) explains refusals.

| Symptom | Cause | Fix |
| --- | --- | --- |
| The agent says it has no Super Artifacts tools. | Missing connection or sign-in approval. | Use [Connect](https://pr-2197-stg.superartifacts.app/docs/connect.md), approve sign-in and start a new chat. |
| A prompt or skill uses a tool name you cannot find in the tool list. | The skill is stale, or the tool belongs to a different product. | Follow `fix` for `unknown_tool`; use [current tool names](https://pr-2197-stg.superartifacts.app/docs/reference/mcp.md). |
| A publish is refused with `plan_limit`. | The workspace's retained storage is full, or a list is over its cap. | A storage-growth refusal does not delete published pages. Check the exact limit before deleting anything (below). Storage limits are on [Plans and pricing](https://pr-2197-stg.superartifacts.app/docs/reference/plans.md). |
| A link opens a page titled **You need access**. | The current audience or signed-in account does not admit you. | Press **Request access**; the author is asked. Or ask them to share it, or open it through a project you can see. |
| Adding an artifact to a project is refused until you confirm. | The project would let its audience read a private artifact. | Tell your agent you mean it and it will confirm, or leave the artifact out. |
| A publish is refused with `missing_index`. | There is no `index.html` page at the top level. | Put `index.html` at the root. |
| A tool call fails with `mcp_timeout` after 55 seconds. | The call took longer than the proxy waits. It may still have finished. | Repeat reads; check before repeating changes. |
| A publish, read or delete is refused with `role_unavailable`. | Your workspace role could not be confirmed. | Repeat the call; the request was refused and nothing was changed. |
| `unauthorized` with a key that works elsewhere. | The key may belong to another environment. Production uses `sa_live_`, staging `sa_stg_`; legacy prefixes can differ. | Ask the agent which account it uses (below), and get a key from that plane's Agents page. |
| You expect search to need an account. | It does not. Docs search runs in the browser from a static index. | Use ⌘K or Ctrl K without signing in. |
| **Domains** or **Metrics** shows a "Coming soon" screen. | Those pages are in the navigation but not built yet. | Nothing to fix; there is no setting behind them today. |

## Documents, secrets and plans

| Symptom | Cause | Fix |
| --- | --- | --- |
| Markdown appears as raw text, or `looks_like_markdown` refuses publication. | Markdown was sent as HTML. | Publish through markdown-viewer so the source is kept. See [Documents](https://pr-2197-stg.superartifacts.app/docs/documents.md). |
| Edit or Export is missing. | You lack Owner/Editor access, or that version has no stored source. | Check the version and role; publish a source-backed document for that workflow. |
| Document co-editing is full. | The document has twenty editors or the workspace has used its separate document-room allowance. | Close unused editors and documents; check [Limits](https://pr-2197-stg.superartifacts.app/docs/reference/limits.md). |
| `approval_required` stops a secret call. | No matching owner-approved grant exists. | Give the owner the approval link and wait. Never paste the credential into chat. |
| Mail sends stop despite a higher member cap. | Another applicable cap or the plan allowance is lower. | An Owner checks default/member caps in People and the Mail plan allowance. |

Solo includes REST and SDKs; unpaid calls are currently logged, not refused. For `403`, check key permission and role.

## Webhooks

Open **Webhooks → Logs** and read the newest attempt.

| Symptom | Cause | Fix |
| --- | --- | --- |
| Your receiver answers 401 and attempts show red. | The signature check failed, and a 401 is not retried. | Check the secret on **Overview**, then **Replay** the message. |
| The signature never matches. | The body was parsed and written out again before checking, or the key was not decoded from after `whsec_`. | Verify the raw bytes, as in [Signing](https://pr-2197-stg.superartifacts.app/docs/reference/webhook-signing.md#the-signature). |
| The timestamp is refused. | Your clock is more than five minutes off, or you verified a queued message late. | Sync the clock and verify on arrival. |
| Nothing arrives. | The endpoint is off, does not list the event, or its agent filter excludes the agent. | Find the message in **Logs**: none listed means no endpoint matched. Check **Events** and **Agents**. |
| An endpoint is **Failing** or off. | It failed many times in a row, or answered 410. | Fix the receiver, turn it on in **Advanced**, then **Recover failed messages**. |
| The same event arrives twice. | Delivery is at least once; a retry or replay repeats the `webhook-id`. | Keep handled ids and ignore a repeat. |

**Find out why my webhook fails**

```prompt
My Super Artifacts webhook endpoint is failing or receives nothing. Read https://superartifacts.app/docs/troubleshooting.md and https://superartifacts.app/docs/reference/webhook-signing.md first. Ask me to open the endpoint under Webhooks and read you its newest attempts: the status, the response snippet and the time. Then check my receiver code against the signing rules: raw body kept as received, the three webhook- headers, the 5-minute tolerance, the key taken from after whsec_, constant-time comparison, a 2xx answer, and dedupe on webhook-id. Tell me the cause in one sentence and change only my receiver, not the secret or the endpoint.
```

## Prompts for the fixes above

**Which account is my agent using?**

```prompt
Which Super Artifacts account and environment are you connected to? Call super_whoami and tell me the handle and the environment in one line. Do not publish anything.
```

**After a timeout**

```prompt
That Super Artifacts call timed out. Before you try again, check with super_artifacts whether it already happened, and only redo it if it did not.
```

**Storage is full**

```prompt
My Super Artifacts storage is full. List my artifacts and their versions, and suggest old versions or artifacts I could delete. Delete nothing until I say which.
```
