Common errors
Diagnose authentication, generation, connection and execution failures.
Start with the exact operation, HTTP status or run state, selected project and installed release. Keep credentials and raw sensitive records out of diagnostic messages.
Authentication and access
401: verify the host and credential. REST API keys useX-API-Key. MCP tool calls accept the same API key or a session bearer token, and report a401inside the tool result rather than as the HTTP status. Listing MCP tools needs no credentials.403: inspect permissions, scope and pending approvals. Knowing a resource ID does not grant access.402: inspect the license or usage remediation in the response and the workspace plan.404: check the ID and project; inaccessible resources can also appear not found.
See Workspace access and REST API.
Generation fails or looks wrong
Inspect the field catalogue and type-specific options. Check numeric ranges, Derived references, nested template IDs and source connections. A successful HTTP response can still contain field error markers; validate values before exporting.
The generation response is an envelope: the rows are in live_data, one object per row. If len(result) or Object.keys(result) reports two items, you are counting the envelope (live_data and dependencies) rather than the rows. See Read the rows.
Connection timeout or TLS failure
Test from the component executing the request. A hosted worker cannot reach a database on your laptop through localhost. Check DNS, routing, firewall rules, credentials and the certificate chain. Configure the deployment's trusted corporate CA where needed; do not disable verification as a routine fix.
Scenario failed, stalled or timed out
Inspect the run log and worker availability separately. Dependency installation can fail before your script starts, and a requirement written in a form the save path refuses is dropped rather than installed; see Python environment.
For memory pressure, process smaller batches or use chunked data jobs. For timeouts, inspect slow target calls and the configured scenario timeout. Cancellation does not undo writes, and a rerun starts at the beginning.
Rate limit or locked resource
For 429, honor Retry-After if supplied and use bounded backoff. The SDKs do not guarantee automatic retries. For 409, inspect the resource state; a locked set must be reviewed and unlocked before changing it.
Missing files or unexpected success
Write outputs under DATAMAKER_WORKSPACE_OUTPUTS, then verify the persisted file. A start acknowledgment is not a completed run; poll the status route. For data jobs, inspect failed/skipped counts even after completion.