Skip to content

Troubleshooting

Fix common SpecsGraph problems with sign-in, Git connections, publishing, reviews, agents and notifications, 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. 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.An Admin checks the pending invitation in Settings, then Users, revokes it and invites again, or copies the invitation link and sends it.
You signed in, but the organisation is not thereThe invitation is still pending, or you signed in with another account.Open the invitation link again while signed in with the account you want, or ask for a new invitation.

Git connections

SymptomLikely causeWhat to do
A repository is missing from the project's repository listThe GitHub App is not installed on it, or the GitLab token cannot reach it.Add the repository to the App's installation in GitHub, or use a token with access. See Connect GitHub or GitLab.
Settings, then Integrations shows no GitHub connection after you installed the AppYou are not an owner of the GitHub organization, so GitHub sent the installation to an owner.Ask an owner to approve the request in GitHub.
A project warns about repository accessThe repository left the installation, the App was suspended, or the token was revoked.Restore access, or point the project at another repository.

Publishing

SymptomLikely causeWhat to do
The task shows Awaiting merge and its pull request is openNothing is wrong: it lands when the pull request merges.Merge it under your usual rules, then choose Check now (or wait up to five minutes).
Publish is refused with task has conflictsA scoped change conflicts with Main.Resolve the conflicts on the Changes page, then publish. See Changes and conflicts with Main.
Publish is refused because another task holds an artefactThat task's pull request is awaiting merge.Merge or close it first.
Publish is refused with open questionsA blocking question on a scoped artefact is open.Answer it, or an Admin overrides with a reason. See Threads, questions and change requests.
The task is Failed: the pull request was closedSomeone closed it without merging.Choose Retry, which reuses the task's branch.
The task is Blocked: files changed in the repositoryA file in the spec folder was edited in Git.Make the change in SpecsGraph and have an Admin choose Overwrite, or revert the edit in Git and publish again.
The task is Blocked: Main movedMain changed since the publish was planned.Publish again.
The task shows OutdatedThe agreement changed after the last publish.Publish again.

Tasks and publishing explains every publication state, and Branches and pull requests how a task reaches your repository.

Reviews and tasks

SymptomLikely causeWhat to do
Accept is refused as staleThe workstream changed on the same fields since the agent staged.Ask the agent to read the workstream and stage again, or withdraw.
Accept is refused with pending dependenciesThe revision refers to another pending revision.Accept with its dependencies (the default in the app), or accept that one first.
Accept group is refused because the plan changedThe agent staged into or out of the plan since you opened it.Review the added or removed members and accept again.
Ready is refused for another personThe project's Ready rule is Not the accepter and you accepted a change the task carries.Choose Ask for Ready.
Complete is refusedThe workstream has open tasks, unrouted changes or a pending proposal, or no Done task.Finish or abandon the tasks, route or discard the changes, accept or withdraw what is pending, or abandon the workstream.

Work items and build status

SymptomLikely causeWhat to do
A Ready task has no work itemsThe project's flow template is empty, or the task was marked Ready before work items existed.Choose Add items from template on the task, or add items by hand.
A merged pull request did not complete the implement itemNeither its title nor its branch named the item, the repository or branch is not watched, the task has several open implement items, or the merge is older than the item's current round.Name the item, such as T-12.1, add the repository in Execution, then Code repositories, or mark the item done by hand. See Work items and delivery.
A deployment did not complete the deploy itemThe item is still blocked, its environment is another one, or the commits since the last deployment do not name the task.Finish the implement item first, then deploy again; check the keys your CI step sends.
An agent's claim disappearedIt sent no heartbeat within 2 hours, so the claim lapsed and the item went back to To do.Have the agent heartbeat with work_item_update while it works, and claim again.
An artefact shows OutdatedMain changed since the code was built.Build the change through a task, or Mark as implemented if the code already matches.
A row says Needs confirmationAn implement item finished without a revision of the artefact routed to its task.Mark the artefact as implemented, or correct the item's artefacts.

Proposals, plans and review covers accepting staged changes, and Workstreams when a workstream completes.

Agents and MCP

SymptomLikely causeWhat to do
401 UnauthorizedThe agent's sign-in was revoked or expired, or its token is missing, expired or revoked, or the client did not expand the variable that holds it.Sign in again from the client. With a token, test with curl as shown in Other MCP clients, then create a new token in Settings, then Access tokens if needed.
403 Forbidden, or a tool error saying access is deniedA Read only connection called a write tool, the project is not included, or the person it acts for is a Viewer.Connect again with Read and write access for the right project, or ask for the Editor role. See Personal access tokens.
The agent reads old contentIt reads Main while the change is in a workstream.Tell it to read scope workstream:WS-n (the AGENTS.md snippet does).
Agents cannot connect at all, for everyone in the organisationThe URL is wrong, or a firewall or proxy on your network blocks mcp.specsgraph.io.Check that clients use https://mcp.specsgraph.io/mcp exactly, and allow outbound HTTPS to that host.

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

Notifications

SymptomLikely causeWhat to do
No notification emailsEmail is Off in Settings, then Preferences, or the kind is turned off.Check your preferences.
An email arrives up to 30 minutes lateYour email mode is Digest.Choose Right away.
The bell shows fewer notifications than you expectThe bell counts the organisation you are in.Switch organisation from the user menu.

Notifications and waiting on me lists every kind and how each reaches you.

Get help

Include what you expected, what happened and the steps that lead there, with any tokens or other secrets removed.

Next steps