Troubleshooting
Find the failing stage and compare configuration with actual data effects
Start with the exact pipeline ID, active version and run ID. Identify whether failure occurred while authoring, validating, queuing, reading, processing or committing output. A valid graph and an accepted run do not prove a successful result.
| Symptom | Likely area | Investigation |
|---|---|---|
| Cannot select an endpoint | Scope/access | Correct workspace, endpoint direction and actor permissions |
| Transform missing | Installation | Enabled capability, installed version and runtime support |
| Invalid edge | Graph | Existing port keys, input/output direction and compatible interface |
| Preflight fails | Configuration | Named node issue, unresolved resource or write-policy binding |
| Accepted but stays queued | Dispatch/runtime | Durable run record and dispatch health; inspect before launching again |
| Source returns no rows | Read contract | Target selectors, query bounds, cursor and source fixture |
| AI extraction/classification fails | Model/runtime | Required prompt/parameters, configured model and actual error |
| Lookup multiplies or drops rows | Transform contract | Key uniqueness, join type and missing-match handling |
| MCP enrichment fails | Remote tool | Installed server, auth, read-only annotation, argument types and rate limits |
| Ontology facts missing | Materialization | Package terms, mappings, fact-store endpoint and actual materializer result |
| Assertion missing or changed | Assertion policy | Invalid-record handling, deduplication, conflicts and review state |
| Egress partially wrote | Destination | Actual committed rows and connector transaction/replay behavior |
| Duplicate rows/keys | Replay | Append mode, prior successful steps and idempotency scope |
| Schedule has no run | Schedule | Enabled state, time zone, next run, actor access and last_error |
A reproducible report
Record pipeline/version/run IDs, the relevant node label and error, installed plugin/capability version, target names, input bounds, expected output and observed output. Include connector cursor/snapshot and whether any external writes committed. Share secret-free diagnostics; keep tokens/passwords in installation settings.
Fix without losing evidence
Edit a new draft and validate it, then save a version and run a dedicated bounded fixture. Compare the new run with the old snapshot. Preserve the failed run rather than explaining it solely from today's draft. If cancellation or retries are involved, inspect completed effects and use connector-supported recovery.
See Runs and recovery for interpreting accepted jobs and Incremental reads for cursor/replay tests.
A pipeline will not run
Save pending edits as a version. Validate and inspect the exact node/edge error. Check endpoint references, installed executable transforms, parameters, and permissions. A valid preflight is not proof that live source data will work.
A run fails or is partial
Open its steps and diagnostics. Fix structural configuration before a new run. Use Recovery for supported resume paths. For uncertain external effects, reconcile target state and receipts before retrying.