Skip to content

Troubleshooting

Fix common SpecsGraph problems with sign-in, the GitHub App, publishing, agents and self-hosted installs, and find out where to ask for help.

Find the symptom in the tables below. Each row names the likely cause and what to do, and links to the page with the details. If nothing here fits, get help.

Sign-in and invitations

SymptomLikely causeWhat to do
An invitation email never arrivesThe address has a typo, or the mail was filtered. On a self-hosted install, SMTP_URL is not set, so no mail is sent at all.Ask an Admin or Owner to check the pending invitation in Workspace settings, then Members, revoke it and invite again. Without mail, they choose Copy invite link and send the link themselves.
You signed in, but the workspace is not thereThe invitation is still pending, or you signed in with a different GitHub account.Open the invitation link again while signed in with the account you want to use, or ask for a new invitation.
Sign-in fails on a self-hosted installThe callback URL or the client credentials of your GitHub App do not match the install.See Check the install.

GitHub App and repositories

SymptomLikely causeWhat to do
A repository is missing from the project's repository listThe GitHub App is not installed on that repository.In GitHub, open the App's installation, choose Configure and add the repository. See Change or remove access.
Workspace settings, then GitHub still shows no connection after you installed the AppYou are not an owner of the GitHub organization, so GitHub sent the installation to an owner as a request.Ask an organization owner to approve the request in GitHub.
A project shows a warning about repository accessThe repository was removed from the installation, or the App was suspended or uninstalled.Restore access in GitHub, or point the project at another repository. Approved proposals wait until then.

Publishing

SymptomLikely causeWhat to do
A proposal is Approved and its pull request is openNothing is wrong. A proposal becomes Published when its pull request is merged.Merge the pull request under your usual rules. See Branches and pull requests.
A proposal stays Approved and no pull request appearsDirect commit is set on a protected base branch, a ruleset blocks spec/* branches, or the repository left the installation.Fix the cause: switch to Pull request, allow spec/* for the App, or restore repository access. Then choose Retry publish on the proposal.
A pull request was closed without mergingSomeone closed it in GitHub. The proposal stays Approved with a warning.Reopen the pull request, or choose Retry publish to open a new one. To drop the change, an Editor or above withdraws the proposal.
A warning about commits to the spec folder made outside SpecsGraphSomeone edited specsgraph/ by hand. SpecsGraph does not import those edits, and stops before overwriting them.Make the change in SpecsGraph as a proposal, or revert the hand edit in Git, then choose Retry publish. The CI guard in Spec files in your repository stops it happening again.

Agents and MCP

SymptomLikely causeWhat to do
401 UnauthorizedThe token is missing, expired or revoked, or the client did not expand the variable that holds it.Test with curl as shown in Other MCP clients, then create a new token in Account settings, then Access tokens if needed.
403 Forbidden, or a tool error saying access is deniedA Read only token called a write tool, the project is not on the token, or the token owner is a Viewer and the tool opens a proposal.Create a Read and write token for the right project, or ask for the Editor role. See Personal access tokens.
Agents cannot connect at all, for everyone in the workspaceThe mcp service is down, or the reverse proxy does not send the /mcp path to it.Run docker compose ps and check the mcp service and its logs, then work through Check the install.

Other MCP clients has the full table for connection problems, including timeouts and missing tools.

Self-hosted installs

SymptomLikely causeWhat to do
Services do not start, or the proxy has no certificateDNS, ports or the first start of Postgres.Work through Check the install.
Repository changes do not show up in SpecsGraphWebhook deliveries failed, often because the install was down or the webhook secret changed.In the App settings on GitHub, open Advanced > Recent Deliveries and redeliver the failed ones.
Everyone was signed out and agents get 401 errorsSPECSGRAPH_SECRET_KEY changed.Expected after a key change. Sign in again and create new tokens. See Configuration.

Get help

Include what you expected, what happened and the steps that lead there. On a self-hosted install, add the version (the SPECSGRAPH_VERSION tag) and logs taken with LOG_LEVEL=debug, with secrets removed.

Next steps