# 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 convenient workflow call times out

Pagination and sequential multi-URL work may need more wall time. Version 0.0.4 keeps the server run durable even when `extract()` or `schema()` stops waiting.

Read `MakraTimeoutError.run_id` and reconcile it with `get_run()` before retrying. A client timeout does not stop the server run. Use `submit_extract()` directly when your application needs to persist the run ID before waiting.

## 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.4-beta/reference/client).