Fix a common problem

This page lets you find the fix for an error you are seeing in Spectrace, grouped by the surface that produced it. Each entry names the exact code or message and the one action that resolves it.

The GitHub App card at Settings → Integrations shows Install Spectrace (or Install on another account when it already lists installations you administer) only to organization owners and admins. Members see the text "Only an organisation owner or admin can install the App." Ask an owner or admin to run the install.

If the card reads "The GitHub App is not configured in this environment.", the Spectrace deployment has no GITHUB_APP_SLUG set (the card checks only the slug; missing credentials fail later, as app_credentials_invalid). This is a deployment problem, not an account problem: an administrator of the Spectrace host must set the GitHub App variables listed in Environment variables and redeploy.

The install came back with an error

After GitHub redirects to Spectrace, a failed connection lands on Settings → Integrations with error=github_install_<reason> in the URL and a message on the page. The <reason> decides the fix.

Reason	What happened	Fix
`github_not_connected`	Your Spectrace user has no GitHub identity bound in this organization. This normally shows as the card message "Connect your GitHub account above to list the App's installations." rather than in the URL: the redirect flow sends you to connect GitHub instead of showing an error.	Connect your GitHub account in the GitHub section of the same page, then retry the install.
`token_invalid`	Your GitHub sign-in expired or was revoked.	Disconnect GitHub, connect it again, then retry.
`sso_required`	The GitHub organization enforces SAML single sign-on and Spectrace is not authorized for it.	Authorize Spectrace for the organization in GitHub, then retry.
`github_forbidden`	GitHub refused to list your installations, usually because the organization restricts OAuth apps.	A GitHub organization owner approves Spectrace, then retry.
`not_org_admin`	The GitHub membership check returned a role other than `admin` (member, billing manager, or a pending invitation).	An owner or admin of the GitHub organization runs the install.
`account_mismatch`	The installation is on a different GitHub account than the one connected to your Spectrace user.	Sign in to GitHub as the account that owns the installation, reconnect GitHub, then retry.
`installation_not_visible`	The `installation_id` in the link does not resolve to an installation you administer.	Start the install from Settings → Integrations rather than from an old link.
`installation_foreign_app`	The installation belongs to a different GitHub App.	Install the Spectrace app from Settings → Integrations.
`unsupported_account_type`	The installation is on a GitHub Enterprise account.	Install on a GitHub organization or a personal account.
`members_permission_missing`	The installation token does not carry the Organization → Members (read) permission, so Spectrace cannot confirm you administer the organization.	On GitHub, open the app's installation settings and accept the updated permissions, then retry.
`claimed_elsewhere`	Another Spectrace organization already connected this installation. Spectrace does not name it.	Uninstall the App from that GitHub account on GitHub and install it again (a fresh install gets a new installation ID that this organization can claim), or install the app on a different GitHub account.
`rate_limited`	GitHub rate-limited the check.	Wait a few minutes and retry; nothing is wrong with the setup.
`github_unavailable`, `installation_payload_incomplete`, `app_credentials_invalid`	GitHub or the Spectrace deployment returned something the claim flow could not use.	Retry in a moment; if `app_credentials_invalid` persists, the Spectrace host's `GITHUB_APP_ID` / `GITHUB_APP_PRIVATE_KEY` are wrong.
`forbidden`	Your Spectrace role in this organization is not `owner` or `admin`.	Ask an owner or admin of the Spectrace organization.
`missing_org`	The install started outside Settings, so Spectrace could not tell which organization to connect.	Open Settings → Integrations and start the install from there.

success=github_app_requested is not an error: you asked GitHub to install the app on an organization you do not own, and a GitHub owner must approve it before Spectrace can claim it.

Nothing happens on a pull request

Verification runs only when all of the following hold. Check them in order.

The repository is covered by the installation. On the GitHub App card, the repository appears in the mapping table; if it does not, add it to the installation on GitHub.
The repository is mapped to a project. A repository set to Not mapped is ignored, and the webhook records skipped: "repository not mapped to a project".
The installation is active. A suspended installation shows "Installation suspended — re-enable it on GitHub" on the card.
The event is one Spectrace handles: opened, synchronize (a push), or reopened. Editing a title or description alone does not start a run.

PR verification

The comment says "no requirement linked"

Spectrace posts this comment when the resolution ladder cannot pick exactly one requirement. The lead sentence tells you which case you hit.

Lead sentence	Meaning	Fix
"No linked requirement found for this PR in project."	Nothing shaped like a reference number was found in the branch name, title, or description, and no changed file has a traceability link.	Put the requirement's reference (for example `sss-050`) in the branch name or PR title, then push a commit or reopen the PR.
"This PR looks like it references `x`, `y`, … but no requirement with that reference exists in project."	The reference matched the pattern but no requirement in the mapped project has that number.	Check the reference on the requirement page and confirm the repository is mapped to the right project.
"This PR touches files linked to several requirements in project, with no clear match."	No reference was found and the top two file-traceability candidates are tied.	Add an explicit reference; Spectrace does not guess between tied candidates.

The comment's own text says a title edit is enough to re-run. Today only a new commit (synchronize) or a reopen re-runs verification, so push or reopen after adding the reference.

The comment asks "which requirement?"

The branch name, title, or description names more than one real requirement and no single source names exactly one. Keep only the primary reference in the branch name or title, mention the others in the description, then push or reopen. The check run for this case is neutral with the title "Several requirements referenced — pick one" and does not block merging.

The comment posted but has no "Full breakdown" link

The footer link points at the Spectrace app and is dropped when the report URL falls back to the PR's own URL. That happens when NEXT_PUBLIC_APP_URL is not set in the environment of the Trigger.dev worker that runs the pr-verification task. If you administer the deployment, set NEXT_PUBLIC_APP_URL in the Trigger.dev environment (not only in the web deployment) and redeploy the worker; the "Browse requirements" link in unmatched comments and the check run's details URL degrade the same way.

The check run failed with "Verification could not complete"

The verification pipeline threw after opening the check but before it could grade the diff (for example the AI provider was unavailable, or the PR diff could not be fetched). A GitHub token failure happens earlier and leaves no check run at all, only a failed verification row. Spectrace concludes the check neutral, never failure, for its own errors. When a requirement had already been resolved, the failed run appears on that requirement's PR verification tab with its error message; open the tab, read the message, then press Re-verify to run again with the same requirement.

Check runs

No check run appears, only a comment

Check runs need an installation token. If your organization has not installed the GitHub App and Spectrace fell back to a member's OAuth token, GitHub refuses the check write and the job continues with only the comment. Install the GitHub App from Settings → Integrations.

The worker logs "GitHub refused" with status 403 for the check run

The installation predates the app's checks: write permission and the organization has not accepted the new permission. On GitHub, open the app's installation page for the organization and accept the updated permissions; the next push creates the check run.

The check does not block a merge on partial results

That is by design. Spectrace verification concludes failure only when a criterion is contradicted. Progress, nothing addressed, unmatched, and pipeline errors all conclude neutral, which GitHub treats as passing for required checks. See Use check runs.

MCP server

The authentication and quota errors below arrive either as an HTTP 401 JSON-RPC envelope ({"error":{"code":-32001,"message":"Unauthorized","data":{"reason":"…"}}}) on the hosted endpoint, or as a tool result with isError: true; the last two rows are startup and install errors.

Reason or text	Meaning	Fix
`MISSING_API_KEY`	No `Authorization` header reached the server, or the stdio process has no `SPECTRACE_API_KEY`.	Send the header with the `Bearer` prefix (a header without it returns `INVALID_API_KEY`). For Claude Desktop through `mcp-remote`, keep `Bearer` inside the `SPECTRACE_AUTH` env value.
`INVALID_API_KEY`	The key does not exist, was revoked, or its owner is no longer a member of the organization.	Create a new key at Settings → Developers and replace it in the client config.
`API_KEY_EXPIRED`	The key's expiry date has passed.	Create a new key at Settings → Developers.
`INSUFFICIENT_PERMISSIONS`	The tool needs a permission your org role does not grant (for example `approvals:write` or `requirements:delete`, which need `admin` or `owner`).	Ask an organization admin, or call `spectrace_whoami` to see your effective permissions.
"The MCP server / agent access isn't included on the free plan. Upgrade to Pro to enable it."	The organization is on the free plan, which allows only `spectrace_whoami` and `spectrace_capabilities`.	Upgrade the organization's plan.
"Monthly agent-call allowance reached (… on the … plan)."	The organization used its monthly allowance of tool calls.	Wait for the next billing period or upgrade.
"Rate limit exceeded. Try again in N seconds."	More than 100 tool calls in one minute from one user (the default; `SPECTRACE_RATE_LIMIT` changes it on stdio and self-hosted servers).	Wait for the window to reset.
"Tool '…' timed out after 30000ms"	One tool call ran longer than the per-call timeout (default 30 s, `SPECTRACE_TIMEOUT` on stdio and self-hosted servers).	Retry; for inline verification, pass a smaller diff.
`Unknown tool: spectrace_eval_run`	The eval tool is hidden unless the server runs with `SPECTRACE_ENABLE_EVAL=1`.	Do not call it from a client; it exists for Spectrace's own evals.
`DATABASE_URL environment variable is required`	You started the stdio or self-hosted server without a database URL.	The stdio server talks to Postgres directly; set `DATABASE_URL`, or use the hosted endpoint, which needs no database access.
`npx -y @spectrace/mcp-server` returns E404	The package is not published to npm.	Use the hosted endpoint, or build from a checkout with `pnpm --filter @spectrace/mcp-server build` and run `node dist/cli.js`.

tools/list shows 36 tools, the reference says 37

The hosted endpoint hides spectrace_eval_run, so clients see 36 tools. The full registry holds 37; the extra one appears only when the server runs with SPECTRACE_ENABLE_EVAL=1. See Tool reference.

Claude Desktop opens a browser window

A browser window means a bad key, not an OAuth prompt. The hosted endpoint speaks no OAuth, so mcp-remote falls back to an authorize flow when it receives a 401. Fix the key in claude_desktop_config.json.

Claude Desktop logs `spawn npx ENOENT`

Claude Desktop inherits the system PATH, not your shell's. Run which npx and put the absolute path in the command field. Logs are at ~/Library/Logs/Claude/mcp-server-spectrace.log on macOS.

VS Code extension

The one-time code that the browser hands back to the editor lives for 120 seconds and can be redeemed once. The details field says which limit you hit: expired, already_used, or not_found. Run Spectrace: Sign In to Spectrace again and complete the browser step within two minutes.

One user can mint at most 10 sign-in codes per minute. Wait a minute, then sign in once.

The extension talks to the wrong host

The extension calls the URL in the spectrace.apiUrl setting, default https://spectrace.io. On a self-hosted or preview deployment, set it to that host's origin and sign in again. See Use the VS Code extension.

Imports

"Unsupported file type"

The document parser accepts .pdf, .docx, .md, .markdown, .xlsx, .xls, .csv, and .txt. A .doc extension passes the file picker, but an older binary Word file is then rejected because it is not a .docx archive — save it as .docx first. Convert anything else to one of those, or paste the text into the wizard's Paste text source. See Import requirements.

"file is …MB — limit is 50MB"

Each file in a document import is capped at 50 MB and one run takes at most 10 files. Split the document or export the text as .txt or .md.

"No extractable text"

The parser opened the file but found no text, which usually means a scanned document made of images. Export the text content as a real Word, Markdown, or plain-text file and import that.