> For the complete documentation index, see [llms.txt](https://rawctx.gitbook.io/rawctx-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://rawctx.gitbook.io/rawctx-docs/documentation/reference/errors-and-troubleshooting.md).

# Errors and troubleshooting

The SDK exposes typed failures so callers can choose retry, user action, or a hard stop without parsing text.

## Error taxonomy

* `UsageError`: invalid arguments or mutually incompatible options.
* `AuthRequiredError`: the operation needs workspace authentication.
* `RegistryError`: the registry failed or could not be reached.
* `ValidationError`: structured input violates its local contract.
* `RawctxError`: common base class for rawctx-specific failures.

`RegistryError` also represents HTTP API failures. Inspect `status_code`, `detail`, and `payload` when present. In particular, a 403 scope or role failure is a `RegistryError(status_code=403)`, not `AuthRequiredError`. The SDK raises `AuthRequiredError` when it cannot resolve credentials before a request. If the registry receives the request and responds with HTTP 401 or 403, the SDK raises `RegistryError` with that status code.

## First checks

```bash
rawctx --version
rawctx login --help
rawctx trust verify --help
```

Then confirm:

1. The command and option are supported by the installed SDK version.
2. `RAWCTX_REGISTRY` points to the intended tenant API for workspace operations, not the Hub browser BFF.
3. The current workspace token is present and authorized for the operation.
4. The application token is bound to the expected `application_key`.
5. The request matches the workspace commitment and retention policy.

## Safe diagnostics

Use the failing subcommand's `--help`, its structured `--json` output when available, and the typed Python exception. The top-level CLI currently accepts `--debug`, but callers should not assume that every command emits additional diagnostics for it. Redact tokens, private URLs, raw prompts, customer data, and trace payloads before sharing any output.

## CI behavior

Proof verification can intentionally return non-zero when a required check fails. In the CI job summary, distinguish that expected policy gate from registry, authentication, or validation failures.

## Decide whether to retry

| Signal                                    | Action                                                        |
| ----------------------------------------- | ------------------------------------------------------------- |
| `UsageError`, `ValidationError`           | Fix input or policy; do not retry unchanged                   |
| `AuthRequiredError` or HTTP 401           | Supply or refresh credentials, then retry once                |
| HTTP 403                                  | Fix token type, role, scope, tenant, or bound application key |
| HTTP 409                                  | Resolve the idempotency or lifecycle conflict                 |
| HTTP 422                                  | Fix request shape, hash mode, or workspace-policy mismatch    |
| Timeout, connection failure, selected 5xx | Bounded backoff; preserve the idempotency key                 |

```python
from rawctx import RegistryError

try:
    run_rawctx_operation()
except RegistryError as exc:
    if exc.status_code == 403:
        raise RuntimeError("Check token type, scope, and application_key") from exc
    if exc.status_code and 500 <= exc.status_code < 600:
        raise  # retry only in a bounded outer policy
    raise
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://rawctx.gitbook.io/rawctx-docs/documentation/reference/errors-and-troubleshooting.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.