Troubleshooting
Most first-run failures are environment or config problems. Use doctor to check the config, framework, CMS connection, and site health before running a full scan.
Start here
npx @cms-lab/cli doctor npx @cms-lab/cli scan --fail-on never --report
Use --fail-on never while building the first baseline so the command writes artifacts even when diagnostics exist.
Common errors
| Symptom | Likely cause | Fix | Command |
|---|---|---|---|
| No Next.js project detected | The command is running in a CMS-only repo, a backend folder, or the wrong workspace directory. | Run scan from the frontend project when you want route checks. For backend-only planning, use CMS-only agent context. | npx @cms-lab/cli agent-context --mode cms-only --preset all |
| Config file not found | cms-lab could not find cms-lab.config.ts in the current directory. | Create the config with init, move into the project root, or pass --config. | npx @cms-lab/cli init; npx @cms-lab/cli scan --config ./cms-lab.config.ts |
| Config validation error | The config shape does not match the schema, or a required provider field is missing. | Run doctor, check the provider example, and keep secrets in environment variables. | npx @cms-lab/cli doctor --config ./cms-lab.config.ts |
| CMS auth failed or CMS unreachable | The CMS URL, repository name, token, permissions, or local CMS server is not available. | Verify the token outside cms-lab, start the local CMS, and rerun doctor before scan. | CMS_TOKEN=... npx @cms-lab/cli doctor |
| Site unreachable | The Next.js app is not running, site.url is wrong, or / is not the health route for a localized app. | Start the app and use site.healthPath or site.healthUrl when the first healthy page is not /. | npx @cms-lab/cli scan --url http://localhost:3000 |
| Route returns 404 or 500 | The CMS document resolved to a URL the app cannot serve, or the app throws while rendering that route. | Check the document slug, route mapping, frontend dynamic route, and data fetch. | npx @cms-lab/cli explain CMS-ROUTE-404 |
| First scan is too noisy | The config maps too many content types at once, or existing CMS content has many known gaps. | Filter by type, run only one check group, or collect a baseline with fail-on never. | npx @cms-lab/cli scan --type page --only routes --fail-on never |
| Report, Markdown, JUnit, or Slack output is missing | The output flag was not passed, the destination path is not writable, or the webhook was rejected. | Use explicit output paths locally and keep webhook URLs in secrets. | npx @cms-lab/cli scan --report .cms-lab/report.html --markdown .cms-lab/summary.md |
When to use doctor
Run doctor after changing config, switching CMS tokens, changing site URLs, or moving a project between local and CI. Run scan after the app and CMS checks pass.
If you only have a CMS/backend, start with the backend-only workflow. Route scans wait until a frontend or staging site exists, but agent-context generation can still be useful before that.
Privacy while debugging
Do not paste tokens, private URLs, raw CMS payloads, webhook URLs, or full generated reports into public issues. Redacted JSON output is the right default for scripts. Share-safe HTML is better when someone needs to inspect report grouping and filters.
npx @cms-lab/cli scan --json > cms-lab-redacted.json npx @cms-lab/cli scan --report --share-report