Help

Troubleshooting common problems

Most problems in Serpel have a short list of causes: a robots.txt that blocks the crawler, a keyword outside the checked depth, a schedule paused for credits or a plan limit, or a token without the right scope. This page lists the symptoms by area with the cause and the fix. Each section links to the guide with the full details.

Crawls and the site audit

Symptom	Likely cause	What to do
The crawl ends at once with “Start URL blocked by robots.txt”.	Your robots.txt disallows the start address for `SerpelBot` or for all crawlers (`*`).	Allow `SerpelBot` in robots.txt, as shown on the SerpelBot page, then start the crawl again. Test the file with the robots.txt checker.
The crawl checks fewer pages than your site has.	The page limit of the project, 100 pages by default, at most 250 on the free plan and 1,000 on Starter and Pro. Or pages that no link and no sitemap points to.	Raise Pages per crawl in the project settings, add the pages to your XML sitemap and link them internally.
Links or text that the browser shows are missing in the crawl.	The page builds them with JavaScript, and the crawl didn’t render it.	Set JavaScript rendering to “Always render” in the project settings. The site audit guide explains the rendering modes.
“Core Web Vitals couldn’t be measured”.	The request to Google PageSpeed Insights failed or its quota was used up.	Nothing to fix on your side. The rest of the crawl is complete, and the measurement runs again with the next crawl.
A crawl doesn’t start, or fails right away.	A crawl for this project is still running, the project is over a plan limit, or the balance didn’t cover the maximum price when the job started.	Wait for the running crawl on Crawls or History, check the limits of your plan, or top up credits and start the crawl again.

Rankings and AI visibility

Symptom	Likely cause	What to do
A keyword shows “not found”.	None of the results within the checked depth belong to your domain or one of its subdomains.	Check a deeper result list. A depth of top 100 costs more per check, see credits and billing.
The position differs from what you see in Google.	Your own search depends on your location, device, language and history. Serpel asks for the exact market, location and device of the keyword.	Compare with the stored result list on the keyword page, and check the keyword’s country, location and device in rank tracking.
A keyword has no position yet.	Adding a keyword starts no check. The position arrives with the next rank check.	Click Check now, or wait for the next scheduled monitoring run.
ChatGPT mentions your brand but never cites you.	The answer names you, but none of its sources is a page of your domain.	See which domains ChatGPT cites for the prompt on the prompt page and work on the content those sources cover. The AI visibility guide explains cited and mentioned.
No Google AI Overview data.	The project setting “Also check Google AI Overview” is off, or Google showed no AI Overview for the prompt.	Switch the setting on in the project settings. Many searches have no AI Overview at all.

Search data and web analytics

Symptom	Likely cause	What to do
Search data stays empty after connecting Google.	The Google account has no Search Console property for the project’s domain, or the first sync hasn’t finished yet.	Check in Search Console that the Google account you connected can see the property. Then give the sync some time and look at History.
Web analytics shows no visitors.	The analytics source isn’t assigned to the project, or the key or property is wrong.	Check the connection under Settings → Integrations and follow the setup in web analytics.

The search data guide explains how often each source syncs and how far back the data goes.

Schedules, reports and emails

Why a schedule pauses

Not enough credits

The next run would cost more than the available balance.
The workspace owner gets one email per pause.
Top up credits and the run starts with the next maintenance round.

no email

Over a plan limit

The workspace has more projects, or the project more keywords or prompts, than the plan allows, or it has a daily schedule without Pro.
If scheduled runs stop without an email, compare the project with the limits of your plan.
Checks you start by hand are refused with plan_limit too. Upgrade or remove items, and everything runs again.

Symptom	Likely cause	What to do
Monitoring runs at an unexpected hour.	The hour of a schedule is in German time (Europe/Berlin).	Pick the hour accordingly in the project settings under Monitoring.
A recipient doesn’t get the report email.	The address isn’t on the recipient list, it unsubscribed through the link in an earlier report, or the email landed in spam.	Check the recipient list in the monitoring settings, where unsubscribed addresses are marked “Unsubscribed”, and send a test email.
No report appears at all.	Reports come only from monitoring runs. Manual rank checks and crawls don’t create one.	Set a schedule or start a monitoring run, as described in monitoring and reports.

Credits, tokens and API errors

Error	Meaning	What to do
HTTP 401 `unauthorized`	The token is missing, invalid, expired or revoked. The CLI exits with code 3.	Sign in again with `serpel auth login` or create a new token.
HTTP 402 `insufficient_credits`	Keyword research or a list refresh costs more than the balance. `details` names the required amount. The CLI exits with code 6. Queued jobs such as crawls and rank checks don’t answer with 402; they fail when they start and show as failed under History.	Top up credits or reduce the job, for example fewer results, keywords or pages.
HTTP 403 `forbidden`	The token lacks a scope, your project role is too low, or an OAuth token was used on the REST API.	The error message names the missing permission. Create a token with that scope.
HTTP 403 `plan_limit`	Projects, keywords, prompts or daily monitoring exceed the plan.	Upgrade or remove items. See credits and billing.
HTTP 404 `not_found`	The item doesn’t exist, or the token is restricted to other projects.	Check the ID and the project restriction of the token.
HTTP 429 `rate_limited`	Too many requests in a short time.	Wait as long as the `Retry-After` header says.
HTTP 429 `budget_exceeded`	The daily credit limit of the workspace or a provider budget is reached.	The daily limit resets at 00:00 UTC. Spread large jobs over several days.

The REST API reference lists every error code with its HTTP status. Add --json to a CLI command to get the full error body.

The CLI can’t sign in: the CLI reference covers device login, SERPEL_TOKEN in CI and every exit code.
A coding agent can’t connect: each MCP guide has its own troubleshooting section, for example the one for Claude Code.
A promo code is rejected: every reason, from a typo to an expired or already redeemed code, gets the same message. Codes work only for the workspace owner with a confirmed email address, once per promotion.

Where to go next

Updated 5 Nov 2026