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.