LoomAI Docs

Appearance

Troubleshooting ​

Every section below follows the same shape: symptom → what it means → what to check, in order. Failures in the app link straight to the matching section where a code is known. If you fix something mid-run, remember Rerun on the record re-fetches the ticket and starts fresh.

When something isn't covered here, see Sending a good report at the bottom.

PAT scopes ​

The single most common source of setup failures is a token that exists but can't see what it needs. The exact requirements per provider:

GitHub — classic PAT

  • Needs the full repo scope. public_repo is not enough — private repos become invisible and read as 404s.
  • For Ticketing use, the same repo scope covers issues.

GitHub — fine-grained PAT (the one that bites people)

  • Resource owner must be the account/org that owns the repo.
  • Repository access must explicitly include the repo — the default is "no repositories" or a selected list that silently excludes new repos.
  • Permissions: Contents: Read and write, Pull requests: Read and write, Metadata: Read (and Issues: Read and write if the same token backs a Ticketing module).
  • Editing a fine-grained token's repository access does not change the token value — you don't need to re-enter it in LoomAI. Just fix the access on GitHub and press Verify again.

Bitbucket Cloud — app password / API token

  • Permissions: Repositories: Read and write, Pull requests: Read and write. The credential also carries your account email.

Azure DevOps — PAT

  • Code: Read and write at minimum. The organization lives on the Version Control module; repos are named project/repo (not owner/repo).

Jira Cloud — API token

  • The credential needs the token, the account email, and the site URL (e.g. https://yourteam.atlassian.net). The token inherits your user's project access — if you can't see a project in Jira, neither can LoomAI.

Shortcut — API token

  • One token is all it needs; it inherits your workspace access.

VCS repo not found ​

Symptom: the Verify button on a Lane repo row fails with not found / 404, or a run fails while cloning a repo that definitely exists.

What it means: the provider returned 404 for the repo. On GitHub and Bitbucket, a private repo your token can't access returns 404, not 403 — it reads as "doesn't exist" but almost always means the token can't see it, not that the repo is missing or must be public.

Check these, in order:

  1. Typo / format — the repo name is owner/repo (GitHub/Bitbucket) or project/repo (Azure). No URL, no .git suffix.
  2. Token scope — walk the PAT scopes list for your provider. For a GitHub fine-grained PAT, the repository allow-list is the usual culprit: the token was created before this repo, or with "selected repositories" that don't include it.
  3. Right credential — the Lane's Version Control module points at the credential you think it does (Modules → your VCS module). One Lane's repos are all verified with that single module's token — it must reach every repo on the Lane.
  4. Owner mismatch — for fine-grained PATs, the resource owner must be the repo's owner (personal token can't see org repos unless the org allows it).

After fixing access on the provider side, press Verify again — tokens don't need re-entering unless the token value itself changed.

VCS auth failed ​

Symptom: Verify or a run fails with an authentication error (401) rather than not-found.

What it means: the provider rejected the token itself — expired, revoked, or pasted incorrectly.

Check these:

  1. The token still exists and hasn't expired (fine-grained GitHub PATs and Azure PATs have expiry dates; classic PATs can be revoked by org policy).
  2. Re-paste the credential in Settings → Credentials (a stray space or a truncated paste is common), then Verify.
  3. If your org enforces SSO, the token must be authorized for the org (GitHub: "Configure SSO" on the token page).

VCS access forbidden ​

Symptom: a 403 / forbidden error on verify, clone, push, or PR-open.

What it means: the token is valid but the action isn't allowed.

Check these:

  1. Write permission — pushing branches and opening PRs needs read and write (repo scope / Contents+Pull requests R/W — see PAT scopes).
  2. Branch protection rules that block the push target.
  3. Rate limiting — heavy verify/clone activity can trip provider rate limits; they clear on their own after a few minutes.

Model key invalid ​

Symptom: runs fail almost immediately (seconds of runtime), often showing a generic failure like "Runner container died unexpectedly" or "Anthropic credential needed." A credential can also expire mid-run: the run works normally for minutes, then dies with an auth line in the log — same cause, same fix.

What it means: Anthropic rejected the run's Claude credential. In the record's log you'll typically find a line like [claude] Failed to authenticate or 401 Invalid authentication credentials. Without a valid key the agents can't start at all, so the run dies fast.

Check these:

  1. Settings → Credentials → Anthropic has a credential for your account — an account with no Claude credential can't run anything.
  2. OAuth token (subscription) mode: these tokens expire. Generate a fresh one with claude setup-token and re-paste it.
  3. API key (metered) mode: confirm the key is active in the Anthropic Console and has access to the model your Lane uses (a key without access to the selected model fails the same way).
  4. Re-run the record once the credential is fixed.

Token expired ​

Symptom: a Lane that worked for weeks starts failing verifies or runs with auth errors, with no config changes.

What it means: an expiring credential (fine-grained GitHub PAT, Azure PAT, Anthropic OAuth token) hit its expiry date.

Check these: which credential is old (Settings → Credentials shows a hint of each stored secret), regenerate it at the provider, paste the new value into the same credential — every module using it picks up the change — and Verify.

No tickets picked up ​

Symptom: you marked a ticket ready but no record appears on the Dashboard.

What it means: the Lane's discovery didn't match the ticket, or the Lane isn't polling.

Check these, in order:

  1. The Lane is enabled (Lanes list — the toggle).
  2. Give it a poll cycle — discovery runs about every 30 seconds; press Refresh on the Dashboard.
  3. Label trackers (GitHub): the ticket carries all of the Lane's discovery labels, spelled exactly (labels are matched by name).
  4. Status trackers (Jira / Shortcut): the ticket sits in the Lane's exact Ready status. On Jira, if the Ticketing module has a project key, only that project is searched — a ticket in another project is invisible.
  5. The ticket hasn't already run — a ticket with an existing record is never re-picked-up by the discovery trigger; re-running takes a distinct signal (see Re-run not triggering).
  6. Done/archived stories (Shortcut) are skipped by discovery on purpose.

Re-run not triggering ​

Symptom: a ticket that already ran won't run again, even though it's labeled / in Ready.

What it means: finished tickets are deduplicated by their run record — the discovery trigger alone never re-runs them. Re-running takes its own signal.

Check these:

  1. Label trackers (GitHub): add the Lane's re-run label (default ai-redo) — re-applying the discovery label does nothing.
  2. Status trackers (Jira / Shortcut): move the ticket back to Ready. This only works when the Lane's In Progress stage is mapped — that's what moved the ticket out of Ready on pickup, making its return unambiguous. If In Progress is unmapped, use the Rerun button on the record instead.
  3. Any run can always be re-run from its record page (Rerun re-fetches the ticket, so your edits are picked up).

Ticket status not updating ​

Symptom: runs work fine, but the ticket doesn't move on the board (or labels don't change).

What it means: lifecycle updates are best-effort — a tracker API failure is logged but never fails the run. On Jira there's a specific rule: status moves go through transitions, so the target status must be reachable from the ticket's current status in your Jira workflow, or the move is skipped.

Check these:

  1. The stage is actually mapped on the Lane (blank stages are skipped by design).
  2. Jira: the workflow allows the transition (e.g. your workflow may not allow Ready → Done directly). Statuses you map on a Lane have to be connected in the Jira workflow.
  3. The record's event log — skipped lifecycle updates are noted there.

Run failed — how to triage ​

Symptom: a record shows Failed.

Where to look, in order:

  1. The failure callout at the top of the record — it names the reason (e.g. Anthropic credential needed, Monthly quota reached) and links here when the cause is known.
  2. The live log — scroll to the end; the real error is usually in the last dozen lines. This matters especially for container deaths, where the headline reason is generic but the log has the specific cause.
  3. Artifacts — if the run got as far as planning/coding, the PRD and design docs show what the agents understood; a wrong turn is often visible there.
  4. Fix the cause, then Rerun. Reruns re-fetch the ticket, so ticket edits are picked up.

Runner container died ​

Symptom: failure reason "Runner container died unexpectedly."

What it means: the container running the agents exited without reporting a result. The watchdog caught it. This is a symptom, not a cause — the cause is almost always in the log.

Check these:

  1. Open the record's log and read the last lines. The most common underlying cause is a rejected Claude credential — a Failed to authenticate line means it's really Model key invalid.
  2. A run that died mid-work with no error lines may have hit host resource limits — re-run it; repeated silent deaths on the same ticket are worth reporting.

Run stuck in one state ​

Symptom: the duration keeps climbing but the state hasn't changed in a long time.

What it means: usually nothing — Coding is genuinely long on real tickets (often many minutes). A truly stuck run is failed automatically by the watchdog after its grace period.

Check these:

  1. Open the record — if the live log is still moving, it's working; leave it.
  2. If the log has been silent well past normal, you can Cancel and rerun.
  3. Runs sitting in Queued aren't stuck — they're waiting for a free run slot (concurrency caps) or, on Optimize Lanes, for artifact generation.

Run timed out ​

Symptom: failure reason "Run timed out."

What it means: the run exceeded the maximum allowed wall-clock and was stopped.

Check these: oversized tickets are the usual cause — split the ticket into smaller, well-scoped pieces (the agents do markedly better on focused tickets), then rerun.

Monthly quota reached ​

Symptom: failure reason "Monthly quota reached"; new runs fail immediately.

What it means: your account hit its configured monthly run cap or token budget.

Check these: the quota resets at the start of the next month; if you need the cap raised sooner, contact support with your account name.

Workspace preparation failed ​

Symptom: failure reasons like "Could not prepare the repo worktree,""Two repos resolve to the same workspace folder," or "No repos configured on the Lane."

What it means: the run failed before any agent started, while assembling the multi-repo workspace.

Check these:

  1. No repos configured — the Lane needs at least one repo row.
  2. Duplicate workspace folder — two repos on the Lane share the same role; roles become folder names, so each repo's role must be unique (frontend / api, not app / app).
  3. Worktree preparation failed — usually a clone problem in disguise: run Verify on each repo row and walk VCS repo not found if one fails. A per-repo base branch that doesn't exist also lands here (Verify checks the branch when one is set).

Rate limited ​

Symptom: a run fails and the log tail mentions rate limit, too many requests, or overloaded.

What it means: a provider throttled the run mid-flight — the Anthropic API (429/overloaded), or your VCS/ticketing provider's API.

Check these: wait and rerun — limits are time-windowed and clear on their own. If it recurs, you're likely running too many concurrent runs against one account: lower the Lane's concurrency, or spread repos across credentials. An Anthropic 429 on a subscription credential can also mean the subscription's own usage window is exhausted.

Disk full ​

Symptom: a run fails and the log tail mentions ENOSPC or "no space left on device."

What it means: the orchestrator host ran out of disk while the run was writing (worktrees, dependency installs, build output).

Check these: this is an operator-side condition — report it. Operators: check the data volume (worktrees + repo caches), docker image/log accumulation, and whether the workspace GC retention window is too long for the disk.

Dependency install failed ​

Symptom: a run fails early in Coding and the log tail shows npm/pip install errors (npm ERR!, ERESOLVE, "No matching distribution").

What it means: the agent couldn't install the repo's dependencies inside the runner, so it never got a working build to code against.

Check these:

  1. Lockfile drift — does a clean install pass locally (npm ci / pip install -r requirements.txt) on the Lane's base branch?
  2. Private registries — the runner has no npm/pip auth beyond the repo itself; a dependency from a private registry will fail. Vendor it or make it public to the runner.
  3. Unusual registry hosts — runner egress allows the public internet, but a registry behind a VPN/LAN is unreachable by design.

Optimization run failed ​

Symptom: an Optimization record shows "Optimization failed" on a Lane with Optimize enabled.

What it means: the generation run (which surveys the repo and drafts the map + guide) couldn't finish. Ticket runs on the Lane still work — they just run without optimization until generation succeeds.

Check these:

  1. The repo verifies cleanly (generation clones it like any run).
  2. Your Claude credential is valid — generation runs on the same key (Model key invalid).
  3. Retry via Generate on the Lane. Very unusual repo layouts can defeat the indexer; if it fails repeatedly on one repo, report it.

Sending a good report ​

When you're stuck, include these five things and support can usually answer in one round-trip:

  1. The record id (URL of the record page) — or the Lane name if nothing was created.
  2. What you expected vs what happened.
  3. The failure callout text (reason + detail), if any.
  4. The last ~20 lines of the record's log.
  5. What you already tried from this page.