Troubleshooting

When something breaks, don't worry — find the matching symptom below and work through the checks top-down. If your issue isn't here, email support@specnote.io anytime, or ask in the chat at the bottom right of the screen.

My AI won't connect to Specnote

Symptom: Asking your AI to "create a test" can't find Specnote, or it says "authentication failed".

1. Not connected at all — In Claude Code, type /mcp and check whether specnote is in the list. If not, walk through Connect Your AI (Install MCP) from the top.
2. Browser auth expired — Pick specnote in /mcp and click "Allow" again. Approval renews itself for 30 days, but can lapse after long inactivity.
3. Token revoked — Check MCP Connection on My Page. If the token was revoked, issue a new one and update it in your settings.
4. Tool not restarted — Right after changing settings, restart your AI tool once. Re-reading the config often completes the connection.

Test creation doesn't go through

Symptom: Your AI stalls while creating a test, or says there's no environment.

1. No site address registered — Specnote fills in steps by walking your real screens, so a test environment (site address) must exist first. See Test Environments & Accounts and register one.
2. Ambiguous workspace — If you have several workspaces, say which one: "the workspace is ○○."
3. Out of credits — Having AI explore your app costs credits. Check your balance in Credits & Plans and top up if needed.

A verification won't start

Symptom: Clicking run does nothing, or it fails immediately.

1. Low on credits — To start a verification, your balance needs to be at least 1 credit. If it's below that, the round won't run — top up if you're short.
2. The site address is unreachable — Open the registered address in your own browser. If you can't reach it, neither can Specnote's servers. If the address changed, update it in the Test Environment tab.
3. It's a localhost address — Servers can't reach an address that only runs on your PC. Register the environment as My computer (LOCAL) instead — see Test Environments & Accounts.

The run group won't start and it says "only after approving the PRD"

Symptom: You try to start a new run group, but verification doesn't run right away — it asks you to approve the plan review (PRD) first.

This isn't an error; it's how it's meant to work. A new run group starts only after a person approves once the plan review (PRD) of "what to verify and by what rules." The flow goes like this.

1. Ask your AI "start a verification round for this workspace," and it puts together the plan review (PRD).
2. In the PRD review on the run-group screen, skim the rules and approve. (You can tell your AI "approve it" to click it for you.)
3. Once approved, the tests are submitted and the first verification runs automatically.

For reference, re-verifying a test you've already made or re-running just the failures works without this approval. The plan review is a gate you pass only "when starting a brand-new run group." For details, see Running and results.

Sign-in steps keep failing

Symptom: Verifications repeatedly get stuck around the sign-in screen.

1. No test account — Member flows need a registered sign-in account. Check Sign-in accounts in the Test Environment tab.
2. Wrong or expired credentials — Try signing in to the real site with the registered account yourself. If the password changed or the account is locked, re-register with fresh details.
3. Environment/account mismatch — Accounts are scoped per environment. Make sure you're not sending staging credentials to the production address.
4. LOCAL environment — Apps on your own computer use the "Sign in on my computer" flow. If the sign-in browser window doesn't open, follow the on-screen guide to start the Specnote helper.

Results flip-flop — passing one day, failing the next

Symptom: The same test alternates between pass and fail.

1. Temporary hiccups — Specnote retries on its own when screens load slowly. If results still wobble, the test itself is usually ambiguous.
2. Check the flaky badge — In the CI tab, tests with a flaky badge are more often "shaky test" than "real bug". Open the steps, check they match today's screens, and tighten the ambiguous ones.
3. Pass criteria drifted — If you see "please re-approve", the definition of success has shifted. Review and re-approve the pass criteria and verdicts stabilize.

CI auto-verification doesn't run

Symptom: Pushing code doesn't trigger verification, or it fails in CI.

1. Check the target address — The most common cause. Make sure the SPECNOTE_TARGET_URL repository variable points to a currently reachable public address.
2. Check the token — Re-issuing a CI token auto-revokes the old one. Update the SPECNOTE_TOKEN repository secret with the new value.
3. Check the CI toggle — Only tests with CI inclusion turned on run in CI. Confirm the switch is on for the tests you expect.

The full setup is covered in Connect CI Auto-Verification.

Code connection (GitHub / direct send) fails

Symptom: GitHub won't connect, or sending code fails or drags.

1. GitHub app scope — When installing the app, make sure the repository you verify was included. For new repositories, widen access in GitHub's app settings.
2. First sends are slow by nature — Around 30–60 seconds for ~100 files. From the second send, only changes go out, finishing in 5–10 seconds.

Still stuck?

• Chat at the bottom right — describe the situation and we'll look at it with you.
• Email — send symptoms to support@specnote.io. If a verification failed, include its result screen (or error code) to speed things up.

For a refresher on the basics, see Key Concepts at a Glance and the FAQ.