Troubleshooting
Diagnose Urlbox CLI problems with urlbox doctor and understand the error codes it reports.
Start with urlbox doctor
urlbox doctordoctor checks your install, config, session, credentials and network in one go, and tells you exactly what's wrong rather than failing cryptically deeper in a command. It's the first thing to run whenever something isn't working.
Error codes
When something goes wrong, the CLI reports one of a small, fixed set of error codes along with a hint describing the fix:
| Code | Meaning | Fix |
|---|---|---|
usage | bad flags or a missing URL | check urlbox <cmd> --help |
validation | the request failed validation | read the hint |
auth | not signed in, or an invalid credential | sign in with urlbox login; in CI check URLBOX_API_SECRET |
forbidden | your plan doesn't allow this feature | check your plan |
not_found | unknown render ID, project or credential | verify the ID or name |
conflict | the change clashes with existing state | read the hint |
rate_limit | too many requests | wait and try again |
server | an Urlbox API error | try again shortly |
network | no connection or DNS failure | run urlbox doctor |
timeout | the render exceeded its timeout | raise --timeout, or use async |
"The screenshot looks wrong"
If the page itself returned an error (a login wall, a captcha, an error page) the render still succeeds (you captured something), but the result flags it so you don't mistake a captcha screenshot for the real page. When that happens, see avoiding being blocked for options like proxies and stealth.
Still stuck?
- Run again with
--output-format jsonto see the full error and hint. - Check your version with
urlbox version, and update withurlbox upgrade. - Found a bug? Report it on GitHub.
- Or just talk to us: support@urlbox.com or urlbox.com/contact.