> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zenrows.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Fix a failed run: read its trace and find the exact next step for every error code.

Every `fetch`/`extract`/`batch` run writes a secret-free record under `.zenrows/runs/<run-id>/`. Read it before reflexively adding more flags.

```bash theme={"dark"}
zenrows trace inspect <run-id>    # raw run record
zenrows trace explain <run-id>    # what happened and why
zenrows trace replay <run-id>     # print the equivalent command to re-run
zenrows trace export <run-id>     # JSON, for piping elsewhere
```

## Error codes

| Code | When it happens | Next action |
| - | - | - |
| `AUTH_MISSING` | No API key is configured | `zenrows login --api-key <your-key>` |
| `AUTH_INVALID` | Zenrows rejected the key | Re-check the key in the dashboard, then `zenrows login --api-key <your-key>` again |
| `DOMAIN_FORBIDDEN` | The target domain is blocked by Zenrows policy | Permanent, the same request fails again with any flags. Use a different source |
| `FETCH_EMPTY_RESPONSE` | The page returned no usable content | Retry with `--js-render` and a `--wait-for <selector>` or `--wait <ms>` |
| `PARAM_CONFLICT_AUTO_MANUAL` | `zenrows fetch` or `zenrows extract` got `--js-render` / `--premium-proxy` without `--manual`. `zenrows batch create` accepts those flags on their own | Drop those flags to keep the automatic default, or add `--manual` |
| `PARAM_PROXY_COUNTRY_REQUIRES_PREMIUM` | `--proxy-country` used in manual mode without `--premium-proxy` | Add `--premium-proxy` (10 credits), or drop `--manual` to use auto mode |
| `POLICY_MAX_CREDITS_EXCEEDED` | The **account** has spent its credit allowance | Credits renew at the end of the billing period — run `zenrows usage` for the date. To carry on now, claim the Free-plan account (if unclaimed) or add credits/upgrade in the dashboard |
| `POLICY_LIMIT_EXCEEDED` | The run exceeds a cap **you** set in `policy.json` (`max_credits_per_run`, `max_pages_per_run`). Batch tasks in Adaptive Stealth Mode count at their 25-credit maximum | Split the run, raise the cap with `zenrows policy set`, or use `--manual` with only the options the sites need (a basic request counts 1 credit, `--js-render` 5, `--premium-proxy` 10) |
| `POLICY_EXPERIMENTAL_DISABLED` | `zenrows browser` used before enabling it | `zenrows policy set allow_browser true`, only once Fetch/Extract genuinely can't do the job |
| `MCP_CLIENT_UNSUPPORTED` | `--client` isn't a known MCP client id | Use one of the supported client ids, or generate a generic config snippet |
| `CAPABILITY_UNAVAILABLE` | The command's backend capability isn't enabled yet | Use a local spec/validation path, or escalate to Protected Fetch/Extract |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.