# Troubleshooting

Start with the exception or workflow outcome, then narrow the problem to client configuration, admission, page access, structural extraction, or durable run state.

## The client constructs but every call is unauthorized

The SDK can construct with a development placeholder when no API key is set. The hosted API rejects it. Confirm that the process environment contains `MAKRA_API_KEY` or pass the key explicitly. Do not print the value while diagnosing.

Catch `MakraAuthenticationError` separately from `MakraPermissionError`. The first means the credential is absent or invalid. The second means it is valid but lacks permission.

## The request fails before network I/O

`ValueError` indicates local validation. Common causes include an empty URL list, an empty schema, an invalid execution mode, a negative pagination count, an invalid country code, or a removed public config key.

Fix the call before adding retries. Local validation failures are deterministic.

## The API rejects the URL

Inspect `MakraInvalidRequestError.field`, `reason`, and `index`. Verify that the URL is public, has a valid domain, uses an accepted port, and contains no credentials or control characters.

An accepted URL can still fail during navigation because the remote page blocks access, requires a CAPTCHA, returns an error page, or never reaches readiness.

## A blocking call times out

Increase `timeout` only after deciding the request should remain blocking. Pagination and sequential multi-URL work need more wall time. For work that must survive a dropped connection, use `submit_extract()` and store the run ID.

If a run ID exists, reconcile it before retrying. A client timeout does not prove the server stopped.

## A stream ends early

The SDK resumes streams after disconnection once it knows the run ID. `MakraStreamError` means it could not reach a terminal event within the retry budget. Use the attached `run_id` with `get_run()` or `stream_run_events()`.

## A run completed but data is missing

Inspect `status`, the URL-keyed `data`, `errors`, and `warnings`. Check whether the missing field was optional on the page, whether only one URL failed, or whether warnings report no matches, fallbacks, schema truncation, alignment degradation, or unavailable validation evidence.

Improve ambiguous descriptions before enlarging the schema. Test the same field against several pages in the class.

## Every page behaves like a cold page

The URL shapes may not collapse to one class, the site's layouts may differ within the apparent class, stored knowledge may be expiring, or a storage version may have invalidated it. Preserve `telemetry_run_id` and compare runs.

## A deferred result is unavailable

Call `get_run()` first. Results are available only after the run is terminal and storage has completed. `MakraResultError` covers malformed or failed result download contracts. `MakraNotFoundError` can mean the run does not exist or belongs to another principal.

## Capture useful evidence

Store your application job ID, Makra run ID, `telemetry_run_id`, target URL, SDK version, terminal state, warning codes, exception type, API error code, request ID, and timestamps. Never store the API key or presigned result URL.

For exact method and exception fields, use the [reference section](/markdown/makra-sdk/v0.0.3-beta/reference/client).