Troubleshooting

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

troubleshooting~3 minVerified v0.162.2

Find the symptom, then the fix. Codes link to Error codes.

Symptom	Cause	Fix
The agent says it has no Super Artifacts tools.	It was never connected, the sign-in was not approved, or the chat started before it was.	Copy your agent's connect prompt from MCP tools, paste it, approve the sign-in, then start a new chat.
A prompt or skill uses a tool name you cannot find in the tool list.	It is a name from before 29 September 2026.	Old names no longer work: the call answers `unknown_tool`, and for a known rename `fix` names the replacement. Use the current names on MCP tools.
A publish is refused with `plan_limit`.	The workspace's retained storage is full, or a list is over its cap.	Published pages keep serving. Ask your agent what to delete (below). Storage limits are on Plans and pricing.
A link opens a page titled You need access.	The artifact is private and you are not on it.	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 is shared or public and the artifact is private: the project would let its audience open it.	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.	Ask the agent to put the page at `index.html`, not in a folder.
A tool call fails with `mcp_timeout` after 55 seconds.	The call took longer than the proxy waits. It may still have finished.	Reading is safe to repeat. Before redoing a change, have the agent check it did not already happen (below).
A publish, read or delete is refused with `role_unavailable`.	The platform did not confirm your workspace role in time. The worker asks up to three times, then refuses rather than guess.	Repeat the call; the request was refused and nothing was changed.
`unauthorized` with a key that works elsewhere.	The key belongs to another copy of Super Artifacts (a plane). Production keys start `sa_live_`, staging keys `sa_stg_`; older keys start `sa_live_` everywhere.	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.	Press ⌘K or Ctrl K on any docs page, signed in or not.
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.

Webhooks

How they work: Webhooks. Open the endpoint under Webhooks and read its newest attempt first.

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.
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

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?

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

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

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.