Troubleshoot a stuck or failed run

This page is organised the way you arrive at it: by symptom. Find the line you are actually seeing, read what it means, do the one thing named. Where a subject has its own page, this one points at it rather than repeating it.

Before you diagnose: where to look, and how to see more

Two habits make every diagnosis below faster.

Where to look — the run, not the task. A task is the definition; a run is one execution of it, and the run is where the evidence lives. Open the task, pick the run, and switch to the Events lens: it is the full ordered event stream, including the failure event and its message. The Tree lens shows the shape (which node failed), Flame/Timeline shows where the time went. In the web terminal, task <id> gives cost, duration and last activity, and logs <id> --follow streams the same events. For the task/run split see Runs and tasks.

How to see more — two independent dials. If the feed looks too thin to diagnose anything, you have two orthogonal controls:

Dial	What it changes	Who may turn it
Verbosity (`density reduced\|chatty`)	Whether the feed shows the agent’s thinking steps and full tool detail. Default reduced.	Anyone, per account
Debug mode (`debug on\|off`)	Whether the feed shows SupaCloud’s own internals — MCP tool calls, scope resolution, automatic gate resolutions, danger escalations.	Only where a workspace admin opened the ceiling

See Set the live-feed verbosity and Use debug mode. They are different axes: verbosity filters events the feed could show anyway; Debug reveals events it otherwise hides.

My agent is not doing anything

“Paused — waiting for your decision”

The run banner reads “Paused — waiting for your decision” — “The agent asked a question or needs approval before it continues. Review the request to resume.” The agent hit a gate: a dangerous tool call, an open question, a visual before/after sign-off, or a model class change.

Decide it. Review request on the banner, or from any surface: approvals / tool-approvals then approve-tool <id> / reject-tool <id> in the web terminal, /approvals in Telegram or Discord, or the inline Approve / Reject buttons on the pushed card.

Every gate carries a timeout policy. A Deny gate auto-denies after a deadline and the agent continues without the action. A Hold gate — deploys, migrations, a mid-run danger escalation, a model class change — blocks forever until a human decides. And for a tool or visual gate, a line that is not a verdict is held, not treated as approval: a stray message re-prints the decide hint instead of unblocking the agent. Full detail in Approve or reject agent actions.

Two honest limits. Whether deciding a danger hold can resume the run depends on the agent harness: only harnesses with a real pause (Claude, Gemini) carry on after approval — for the others the gate card says so and names your actual next step (restart, or cancel). And a hold whose task has already ended no longer waits forever: it is closed automatically as expired, since there is no agent left to resume.

“Paused — usage window full”

The banner reads “Paused — usage window full” — “The provider’s prepaid window is exhausted. This run resumes automatically when the window refreshes.”

Do nothing. This is a subscription (OAuth plan) provider whose rolling window is full; the run picks itself back up when the window refreshes. If you want to know how full and how soon, open Reports → Usage or run usage. See Track usage and budget.

“Agent paused — type a message to resume”

On the task detail, a pause badge sits above the message box: “Agent paused — type a message to resume”, with the input placeholder “Agent is paused — type your instruction and send…”. The harness is waiting on you, not on a gate — nothing will resolve this on a timer.

Type the instruction and send it (or intervene <id> <message> from the web terminal, /intervene from chat).

“Pinned runner offline — waiting”

The run’s runner line reads “Pinned runner offline — waiting”. The task is pinned to one specific runner and that runner is not currently reachable, so dispatch waits for it rather than silently sending the work elsewhere.

Bring the runner back (runners lists the fleet with status), or remove the pin so the work can go to any matching runner. For what a runner is and how it connects, see The runner fleet.

Nothing picks up the work

“No runners are available to this workspace yet”

Settings shows “No runners are available to this workspace yet. An organization admin can enroll one or grant an existing runner to this workspace.”

This is a grant problem, not an outage. An edge runner is untrusted by default: until it is granted at least one workspace it is dispatched nothing, even while it is online and idle. The message names the fix — an organization admin enrolls a runner or grants an existing one to this workspace.

“No recent heartbeat — the runner may be unreachable”

The runners board marks a row Stale with the tooltip “No recent heartbeat — the runner may be unreachable.” (with Never in the Last heartbeat column if it has never reported).

The runner process is down, or its outbound connection to the hub is blocked. It connects outbound-only over HTTPS, so check the runner host and its egress — not your inbound firewall. A stale runner is skipped by dispatch and its work is re-queued.

A provider circuit breaker has tripped open

Under Operations the Circuit breakers card — “Provider and project breakers currently tripped open or recovering” — shows a breaker as Open instead of “All breakers healthy.”

A breaker trips after three consecutive failures of the same kind against the same provider or project, and while it is Open requests fail fast or fail over instead of hammering something that is already down. It recovers by itself: after a 60-second cooldown it moves to Half-open, and the first successful call closes it. A still-dead provider simply re-opens on the next failure.

You do not reset a breaker. Fix (or wait out) the underlying outage; the state is durable, so a tripped provider stays tripped across a server restart until it genuinely recovers.

I hit a limit

“Plan limit reached”

A toast appears: Plan limit reached — “This action hit a limit on your current plan. Upgrade for more capacity.” — with an Upgrade plan link. The server answered the request with 403 and the code quota_exceeded, carrying the structured detail an API client sees as, for example, Quota exceeded for 'apps.max_count' (5/5) plus an upgrade URL.

This is an entitlement ceiling on a count (for example the number of Apps), not a spend or usage wall. Nothing waits and nothing retries: the action did not happen. Either free up capacity under that key or upgrade.

A model ran out of quota mid-task

The live feed says the pinned model hit its quota and the task is continuing on another model of the same class — or an approval gate appeared asking whether to fall back to a weaker class.

Same-class switches are automatic; you need do nothing. A class change is never automatic, and its gate waits indefinitely — the task stays blocked rather than being silently degraded. The full mechanism, the class chains and the limits that stop a runaway are in Handle a model quota wall.

“Workspace monthly AI budget exhausted”

Launching fails with Workspace monthly AI budget exhausted ($120.00 spent or reserved). Increase the cap or disable hard stop. — or its per-provider sibling Provider 'anthropic' monthly AI budget exhausted. Increase the provider cap or disable hard stop. The AI Budget card shows the status chip Blocked. A related message, Workspace monthly AI budget has no room for another in-flight task ($5.00 reserved per run). Increase the cap or disable hard stop., means the cap has no headroom left to reserve for one more concurrent run even though it is not yet spent.

Three things are worth knowing here:

The budget governs API-mode (pay-per-token) agents. It does not cap a subscription provider — that one is metered by its usage windows, which is the “Paused — usage window full” case above, not this one.
Hard stop at cap is what turns a warning into a refusal. With it off you keep running past the cap with an alert status; with it on, new runs are blocked.
With hard stop on, an in-flight run can also be cancelled when the cap is crossed; the run’s failure event records “Budget hard stop cancelled in-flight task”.

Raise the monthly cap, raise the provider cap, or turn hard stop off — see Track usage and budget.

The run failed

“Git clone failed — check the repository URL, branch, and credentials”

The exact message is “Git clone failed — check the repository URL, branch, and credentials.” Work through it in that order, because the three failures look identical from the outside: the repository URL (typo, wrong host, private repo), the branch (a default branch that no longer exists), then the credential.

If the URL is an SSH URL you will get a sharper message instead: “This SSH URL needs an SSH-key credential. Either add one to the project or switch the URL to HTTPS and use an access-token credential.”

“Could not list repositories” or an access-token/SSH mix-up

Picking a repository fails with Could not list repositories from {provider} (HTTP {status}). Verify the credential and the required scopes., or with “The API request could not be built. Check that an access-token credential is selected instead of an SSH credential.”

A Git credential has a kind, and the two kinds are not interchangeable. An SSH Key authenticates the git transport — clone and push. An Access Token authenticates the provider’s API — listing repositories, reading issues, opening pull requests, repository sync. So:

Listing, issues, PRs, sync → Access Token. Repository sync says so outright: “Repository sync requires an access-token credential. SSH credentials can be used for clone and push after import.”
If the token is the right kind and it still fails, the HTTP status in the message is the answer: 401 means the token is wrong or expired, 403 normally means it is missing a scope.

A marketplace connector fails at run time

A connector run fails with an error that reads like a SupaCloud fault — a bare 401, a refused login, a timeout — when the cause sits in the third-party system the connector talks to. The install wires up the SupaCloud side (the resource, the credentials, the sandbox) and cannot change what the other system requires: a WebDAV account with no local password, a bank that wants a registered product ID, a mailbox with two-factor authentication that needs an app-specific password.

Create the resource under Resources and prove the credentials reach that system before you blame the connector. The prerequisites that come up in practice are listed in Install a marketplace connector.

A credential, integration or setting refuses me

A secret value cannot be shown again

There is no reveal button, and that is the design: a saved secret is write-only. The UI says as much where it can — “Stored encrypted and never shown again. Re-enter it whenever you save changes.”, “Write-only — never displayed again”, “Secret values are never shown.”

You do not recover a value from SupaCloud; you replace it. Rotate the credential at the source and enter the new value here. See Manage secrets in the UI.

A workspace credential is being ignored in favour of the organization’s

Normally the most specific scope wins — personal, then workspace, then organization. When an organization credential carries the Locked flag it inverts that: “Locked: this organization credential overrides workspace and personal credentials of the same name.”

A workspace admin cannot override a locked organization credential; only an organization owner or admin can unlock it. This is intentional — it is how a billing-relevant key is enforced across every workspace. Manage secrets in the UI has the precedence table.

“Debug is disabled by a workspace admin.”

Turning Debug on returns exactly “Debug is disabled by a workspace admin.”

The workspace allow_debug ceiling is off by default and the check is fail-closed and enforced server-side, so no surface — web terminal, Telegram, Discord — can reveal internals while it is shut. A workspace admin opens the ceiling once; each user then activates Debug for their own session. See Use debug mode.

`/link` is rejected in chat

Linking a chat account fails, and the reason differs by platform:

Message	What it means
“For your security, send /link in a direct message to the bot — not in a server channel, where the code would be visible to others.”	Discord accepts `/link` only in a DM. In a server channel the code would be public, so it is refused outright.
“This Discord account is already linked to a different SupaCloud user.” / “This Telegram ID is already linked to another account.”	The chat identity belongs to someone else. Unlink there first.
“Invalid or expired link token. Generate a fresh token in Settings > Telegram.” / “That link code is invalid or expired. Generate a new one in SupaCloud.”	The one-time code was already used, or it expired. Generate a new one.

“Microphone access blocked”

Voice input reports “Microphone access blocked. Click the lock icon left of the URL, set Microphone to Allow, then reload the page.” — which is the whole fix, in order. Two neighbours: “No microphone found. Connect one or use the Upload audio option.” and “Microphone is currently used by another application. Close it and try again.”

This is a browser permission, not a SupaCloud setting, so no admin can grant it for you. See Use voice input.

Message	What it means	What to do
“Single sign-on is not available for that organization. Please sign in another way.”	That organization has no usable OIDC single sign-on configured (or its entitlement is not active).	Sign in with a password or a linked social provider; ask an organization admin to finish the SSO setup.
“This verification link is invalid or has expired. Request a new one from your account.”	An email verification or magic link was already used, or it aged out. Links are single-use on purpose.	Request a fresh one; do not re-send the old mail.
“You can’t remove your only sign-in method. Add a password or another provider first.”	You are unlinking the last thing you can sign in with, which would lock you out. Refused by design.	Add a password or link a second provider, then unlink.
“Your account is still waiting for administrator approval.”	The account exists but has not been approved on this instance.	Wait for, or ask, an instance administrator.

Google and GitHub sign-in — including the fact that a provider email which already owns an account is never auto-merged, and that an armed two-factor code is still enforced on social login — is covered in Sign in with Google or GitHub.

If the error body carries the code database_error, docker_error, vault_error or internal_error, the message you got is all the client is ever shown: those four collapse to a flat “Database error”, “Docker error”, “Vault error” or “Internal error” before they leave the server. It is not a bug and not a truncation — it is a redaction, so a SQL statement, a vault path or an internal panic message can never reach a browser. Every other error class keeps its real, user-facing text, which is why the rest of this page can quote exact strings and these four cannot.

There is nothing further for you to read here, and retrying rarely helps. The detail exists only in the server log. Hand the case to an instance administrator with three things: the timestamp, the run id (or the task id and the page you were on), and which of the four codes you saw. That is enough to find the matching logged entry, which carries the full cause.