Skip to main content
How-to guideApplies to: Unified engine deployments
Start with the run identity and the exact phase or error. Separate scheduling, waiting, execution, publication, and notification delivery before changing the definition.

​
A run did not appear

Check whether the workload is saved, active, and due. Manual workloads need an explicit start. Paused workloads block new runs. Completed one-time schedules have no future due boundary. Check missed-run and overlap policies, the next due time, and scheduler backlog limits. An occurrence skipped by policy is different from an execution failure.

​
A run exists but is waiting

Do not increase query memory for a scheduling wait. Do not add workers for a sensor that is correctly waiting for a completion marker.

​
Validation fails

Check task names, graph cycles, missing predecessors, duplicate incoming aliases, mixed initial query settings, parameter types, and the schedule expression. Cron needs the engine’s seconds field. Definition validation does not execute Python or prove source permissions and runtime schemas. A definition can validate and later fail during allocation or execution.

​
A relation or alias is missing

If the relation is a stored table, check catalog, namespace, spelling, and access. A catalog named default is not automatically a configured writable Iceberg catalog. If it is an upstream result, check the incoming connection and result alias. An ordering-only dependency does not supply rows. Running a dependent task’s SQL by itself in Workbench does not recreate its upstream inputs.

​
A parameter is rejected

Check required values, nullability, allowed values, and types. Do not quote a named binding in SQL. Scheduled runs need defaults for required values. Window bindings require a recorded window, and incremental workloads use fixed defaults.

​
A task failed without retrying

Check the effective attempt limit and failure category. Invalid SQL is not transient. Python needs explicit replay permission. Writes and source connectors must support safe replay. An uncertain outcome blocks automatic repetition even with attempts remaining.

​
A selective rerun is blocked

Read each entry in the preview’s blocked map. Include tasks without successful reusable outcomes and any upstream tasks whose required result has expired. Wait for source-run cleanup to finish. Streaming and incremental cursors cannot be repaired with selective reruns.

​
A backfill excludes a window

Compare its preview reason with the reprocessing policy and matching historical runs. Missing, failed, and all select different histories. Active, uncertain, or unavailable run history is not proof that a repeat is safe. Check range alignment and the saved schedule revision.

​
A notification did not arrive

Read delivery history separately from run status. Check destination URL, secret resolution, external HTTP availability, response status, attempt count, and last error. A failed notification does not change a successful execution into a failed one. Retry delivery after correcting the destination; do not rerun the data workflow just to resend an event.

​
The response was lost or a write is uncertain

Recover the original submission with its existing identity and identical request. Do not create a fresh append because the browser timed out. Keep the original run and inspect task attempts, commit receipts, and destination evidence. For OutcomeUnknown, let the original execution’s recovery establish the outcome. Cancellation is not rollback, and another execution can repeat external effects.

​
Collect useful evidence

Record workload ID, revision, submission ID, occurrence ID, run ID, task name and ID, attempt ID, effective parameters, window, phase timestamps, exact error, and commit details. Include backfill or notification event IDs when relevant. Use Inspect runs and attempts for execution details and Observability for instance-wide evidence.
Last modified on November 4, 2026