# Troubleshooting

> When the connection fails, a verification won't start, or sign-in steps keep failing — here are the most common symptoms with causes and fixes, in the order worth checking. Most issues resolve by working top-down.

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)](/en/docs/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](https://specnote.io/en/mypage). 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](/en/docs/test-environments) 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](/en/docs/billing-and-credits) 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](/en/docs/test-environments).

## 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](/en/docs/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](/en/docs/connect-ci).

## 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](/en/docs/key-concepts) and the [FAQ](/en/docs/faq).

---

Source: https://specnote.io/en/docs/troubleshooting