> ## 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={null}
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`           | `--js-render` / `--premium-proxy` passed without `--manual`     | 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`          | Out of credits, or over `max_credits_per_run`                   | Claim the Free-plan account (if unclaimed), or add credits/upgrade in the dashboard         |
| `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                    |