In short
- Run npx serpkin status first. It separates a key or server problem from a local agent or deploy problem.
- Serpkin needs Node 22 or newer, and an agent must restart after setup to see the MCP server.
- A 401 on a preview is usually deployment protection, not a broken mission.
- When asking for help, include the site id, error code and run URL, and never include a key or token.
Most Serpkin problems are one of five things: an old Node version, a key that was revoked, a site that is not verified, a preview that is protected, or a plan limit. This page walks through each in the order worth checking, with the exact message you will see and the fix. If none of it matches, the last section says what to send us.
Start with these three commands
Before changing anything, collect the state. These commands are safe and print no secrets.
| Command | What it tells you |
|---|---|
node --version | Whether you are on Node 22 or newer, the minimum the CLI supports |
npx serpkin status | The site, ownership state, data level, next mission and credits |
npx serpkin --version | The CLI version, so we can tell whether an update fixes it |
If a command fails, copy the whole error, not just the last line. Serpkin errors usually include the fix in the message. Never paste an agent key, an Anthropic key or a password into a support message.
Setup and sign-in problems
The command does nothing, or npx downloads an old version
Check Node first. Serpkin needs Node 22 or newer. If you use a version manager, switch to a current LTS release and run the command again. A stale npx cache can also serve an old package; npx serpkin@latest forces a fresh download.
The browser code expired
The sign-in code is short lived. If the browser page says it expired, run npx serpkin again and approve the new code. Make sure the code in the terminal matches the code in the browser before approving: that match is what stops someone else from approving a login they did not start.
The key is invalid or revoked
A 401 means the agent key is missing, revoked or belongs to another workspace. Run npx serpkin init --login to sign in again, or create a new key in Settings, under Agent setup, and set it as SERPKIN_API_KEY. Revoking an old key is the right move if it was ever pasted into a chat, a commit or a log.
The wrong server is configured
.serpkin.json stores the server and site id. If you moved from a self-hosted server to serpkin.com, or the other way around, pass --server explicitly or remove the file and run setup again. The CLI asks before it switches servers when the file and the flag disagree.
Your agent cannot see Serpkin
Setup connects the agents it finds, but an already-running agent will not pick up a new server until it restarts. Quit and reopen Claude Code, Cursor or Codex, then check the connection.
| Agent | What setup writes | How to check |
|---|---|---|
| Claude Code | The Serpkin plugin, or a project MCP entry | Run /mcp in a session and look for serpkin |
| Cursor | .cursor/mcp.json and a project rule | Open Cursor settings, MCP, and confirm serpkin is connected |
| Codex | ~/.codex/config.toml and a section in AGENTS.md | Start a new session and ask what SEO to do |
If the entry exists but calls fail with 401, the key in that config is stale. If calls fail with a network error, check a proxy or firewall that blocks the Serpkin server. Corporate TLS inspection can also break the CLI; configure your proxy's certificate or use a network that does not inspect traffic.
In Claude Code, /serpkin:next is the fastest test. In any agent, ask "What should I do for SEO?" and watch whether it calls a Serpkin tool. If it answers from general knowledge without calling a tool, the server is not connected.
Scans and indexing problems
The site is unverified, so only a few pages are read
Until ownership is proven, a scan is a preview: the homepage plus up to five same-origin pages linked from it. Verify with Search Console, a TXT record or the verification file to unlock full scans and site watch. See Getting started.
Pages are missing from the scan
A page is skipped when robots.txt disallows it, it returns a non-200 status, it needs a login, or it is only reachable through JavaScript navigation. Check the page in a private window with JavaScript off. If the content is empty, the page is client-rendered; Serpkin can render a limited number of pages on paid plans, but the server HTML still matters because that is what Google sees first.
The preview is unreachable
Deployment protection returns 401 or 403. Allow Serpkin through it, or check a public preview. Previews must be on your own domain or a subdomain, or on *.vercel.app, *.netlify.app or *.pages.dev. A URL on another host is refused before any request is made.
robots.txt blocks the check
If robots.txt disallows SerpkinBot, the tool reports it instead of fetching the page. That is the correct behaviour. Remove the rule for the paths you want checked, or test with a URL that is allowed.
No missions, or the wrong ones
- Everything is done: the queue may be empty because open missions were completed, dismissed or resolved. New ones appear after the next scan or data refresh.
- The site is watch-only: after a downgrade, extra sites keep their history and weekly watch but get no new scans, research or verification. Resume or upgrade to unlock them.
- The data level is low: a new site without Search Console and without rankings gets foundation fixes from the scan first. Connect Search Console to unlock query-driven missions.
- A mission was dismissed: dismissed missions stay hidden for 180 days. Restore one from the site's mission list if you want it back.
Missions are ranked, not random. If the top mission looks small, it is usually because it blocks indexing or because it is already in progress. Finishing it moves the queue forward faster than skipping it.
Verification fails
| What you see | Likely cause | Fix |
|---|---|---|
| HTTP 401 or 403 | The preview is behind deployment protection | Allow Serpkin through, or verify on production after deploying |
| The page still shows the old version | The deploy or CDN cache has not updated | Wait for the deploy, purge the cache, then verify again |
| A check says noindex | The page or a header adds noindex | Remove it, or accept it if the page should not be indexed |
| Canonical points elsewhere | A template or CMS setting overrides it | Make the canonical absolute and self-referencing |
| Title, description or H1 missing | The change did not reach the rendered page | Check the deployed HTML, not only the source file |
| Sitemap or robots.txt fails | The file is missing, invalid or blocked | Fix the response, then verify again |
Verification keeps its history, so a failed attempt does not erase the mission. Fix what the checks reported and run it again. For a preview check from the terminal, npx serpkin check <preview-url> exits 1 on regressions and 2 on errors, which makes it usable as a CI step.
Search Console problems
No property found
The Google account you approved must already have access to the property. Add the site in Search Console with that same account, then reconnect. Domain properties and URL-prefix properties are different; connect the one you actually use.
Needs reconnect
Access expired, was revoked, or the property permission was removed. Earlier data is kept but no longer used for new missions. Reconnect from the site panel and the daily sync resumes.
Connected but the numbers look old
Search Console data lags by about two days, and Serpkin ends its 28-day window two days back for that reason. A brand new site can also have fewer than 100 impressions over 28 days, in which case missions use scan and search data until traffic grows.
Limits, credits and pauses
When an action would exceed a plan limit, Serpkin refuses that action and says which limit it hit and what the next plan includes. Nothing is deleted and existing work keeps running. Credits reset on the 1st at 00:00 UTC; missions, scans and reviews reset on the same schedule.
A 402 with CREDITS_EXHAUSTED means the research costs more than you have left. A SEARCH_DATA_PAUSED message means a monthly safety cap or the shared Free budget is exhausted; it gives the resume date. In both cases, scans, missions, site watch and Search Console keep working. Credits has the full table.
Weekly pull requests
| Symptom | Fix |
|---|---|
| The run skips with a notice | A pull request labeled serpkin is still open. Review or close it |
| No open mission | Nothing to do yet. Wait for the next scan or data refresh |
| 401 from Serpkin | Set SERPKIN_API_KEY again with a fresh key for this workspace |
| CI did not run on the PR | Add the optional SERPKIN_PR_TOKEN secret, or run CI by hand |
| The change touched files the workflow does not allow | Nothing was pushed and the mission was dismissed. Restore it and make that change yourself |
| The schedule stopped | Public repositories disable scheduled workflows after 60 days without activity. Run it once by hand |
The run summary explains which job stopped and why. Read it before changing secrets; most failures are a missing variable, not a broken workflow. Setup details are in Weekly pull requests.
Billing problems
If the plan did not change after payment, refresh Account once. Creem's webhook usually arrives within seconds but can be delayed. If a renewal failed, the subscription is in past_due and the paid plan stays active while Creem retries; update the card in the billing portal. Invoices and receipts are in the same portal. See Billing.
If it is still broken
- Reproduce it once
Write down the exact steps, the command or page, and the time. One clean reproduction is worth more than a long description.
- Collect the safe details
Include the site URL, the site id from
.serpkin.json, the CLI and Node versions, the error code and the full message. For a weekly run, include the run URL. Never include a key, a token or a password. - Contact us
Use the contact address on the About page. For billing, write from the email on the Serpkin account and include the invoice date. For privacy or deletion questions, say so in the subject so it reaches the right person.
Questions
Why can't my agent find Serpkin?
Restart the agent after setup, then check the MCP connection: /mcp in Claude Code, MCP settings in Cursor, or a new session in Codex. A 401 means the key is stale.
Why does verification fail on my preview?
Most often the preview is behind deployment protection and returns 401 or 403. Allow Serpkin through it, or verify on production after deploying.
Why did my weekly run skip?
A pull request labeled serpkin is still open, or there is no open mission. The run summary says which. Review or close the pull request, and the next run continues.
Does a failed scan use a scan from my allowance?
A scan that cannot start because of a plan limit is refused before it runs. If a scan starts and fails partway, the job history shows its status and any credits involved are handled by the same settlement rules.