Troubleshooting workflow execution
Diagnose workflow drafts, connections, approval previews, simulations, and unsupported execution paths using grounded product states.
Troubleshooting workflow execution
Workflow Agent currently troubleshoots drafts and simulations rather than live workflow execution. Diagnose the state that is actually present: draft construction, app detection, route readiness, connection setup, approval preview, simulation, or disabled activation. The tables below avoid remedies that would imply external writes, live schedules, webhooks, or MCP calls.
Draft issues
A draft can fail to form when the description is ambiguous, an app is not represented in the loaded source, or the requested behavior exceeds the current linear preview model.
| Symptom | Cause | Correction |
|---|---|---|
| Wrong apps detected | The description does not distinguish source and destination roles. | Rewrite the prompt with the event, source app, destination app, and action. |
| No app relationship appears | The production source may be unavailable, the fixture may be limited, or the pair is absent. | Confirm the loader source and keep the pairing unresolved. |
| Steps are out of order | The outcome combines several operations or hides a dependency. | Reduce the workflow to one ordered path and regenerate. |
| Condition is not represented | A general branch editor is not verified. | Express one supported check plainly or split the design into separate drafts. |
| JSON and visible steps differ | The builder views are inconsistent. | Keep the draft unapproved and capture the mismatch for implementation review. |
Do not repair a draft by adding secrets, inventing fields, or assuming a connector. The goal is an understandable definition, not a passed status at any cost.
Connection issues
Connection failures are often more specific than “integration unavailable.” Read the state reported by the integrations surface and relate it to the candidate execution route.
needs-setup points to missing configuration. expired indicates that the credential should be replaced. config-preview permits inspection only. dry-run supports a no-write route test. live-blocked and disabled prevent execution.
If a configured credential is not recognized, compare the app identity, route mechanism, and environment. The connection may belong to another app or bridge. Do not repeatedly paste the secret into different fields. Exact credential encryption, retention, and rotation behavior remain under review.
A missing webhook, MCP, or schedule configuration may be a product limitation rather than a credential problem. Follow the dedicated page before attempting another connection.
Approval issues
Approval packet previews do not accept decisions. If the builder shows an approval gate and the approvals page shows disabled controls, the gate is functioning as a design boundary.
Confirm that the packet identifies the proposed action, route, reason for review, and supporting simulation evidence. Missing evidence should be added to the draft or preview, not replaced with a fabricated approval.
No approval has been requested, granted, or denied in the current surface. A card that looks complete is still not a signed runtime decision. Keep the workflow blocked and involve the appropriate product or security owner when the proposed action needs policy review.
Simulation failures
A simulation evaluates the draft without contacting external apps. Failures commonly reflect the definition or readiness state rather than remote service behavior.
| Result | Meaning | Response |
|---|---|---|
| Draft validation failed | Required steps or inputs are inconsistent. | Correct the definition before another simulation. |
| Route unavailable | The app action has no usable candidate path. | Leave it unresolved or choose a represented preview route. |
| Credential missing | The route requires setup. | Inspect the matching connection category. |
| Approval required | A sensitive action is gated. | Retain the gate; decisions are not live. |
| Policy blocked | The action violates a current control. | Do not retry or bypass the policy. |
| Connector live-blocked | The route is present but execution is disabled. | Use configuration or dry-run output only. |
A passed simulation does not prove external success. It confirms only that the no-write preview accepted the current draft and prerequisites.
Unsupported actions
Several visible concepts are intentionally non-live:
- workflow activation remains locked;
- generated connector cards can keep
canExecute=false; - live webhook ingress and outbound delivery are unverified;
- MCP connections, process spawning, discovery, and calls are disabled;
- schedules have no verified configuration or executor;
- approval decisions are disabled;
- retry and replay of preview records are unavailable;
- many integrations can be draftable or simulatable without being executable.
When a requested action falls into this list, the correct response is to stop at the supported preview boundary. Do not use a guessed API, endpoint, command, or route to work around the product state.
Debugging checklist
Use this checklist once, after the symptom has been assigned to a specific domain:
- Confirm that the workflow description names the event, source, destination, and action.
- Check whether the app source is production-derived or fixture fallback.
- Compare route status with the candidate execution route.
- Inspect the connection state without exposing the secret.
- Verify that every step input has a visible source.
- Keep approval and policy gates intact.
- Run validation, then request a no-write simulation.
- Compare the simulation result with the draft and read-only JSON.
- Treat preview records as local-safe or fixture-backed, not durable production history.
- Stop when the product reports live-blocked, disabled, coming soon, or unsupported.
For implementation review, include the draft identifier or description, the affected step, route status, connection state, simulation result, and any evidence record that does not contain secrets. Avoid reporting a “live execution failure” when the product never attempted execution.
Route-readiness diagnosis
When an app pair is detected but the draft cannot progress, compare route status and execution route. suggested_only with none means the relationship is conceptual. bridge_available with a named bridge can still require provider setup. api_mcp_possible needs a verified API or MCP implementation, which may remain disabled. coming_soon is not an error to retry.
Also inspect whether the loader used the production source or fixture. A fallback can explain why an expected app, pair, or capability is absent.
Definition and data problems
A simulation can expose missing values even when the step sequence looks correct. Trace every input to the prompt or an earlier step. If the value is a credential, move it to the connection model. If it is supposed to come from an external app, the preview can describe the field but cannot confirm its live schema.
Avoid solving an input problem with invented defaults. An explicit unresolved field is safer than a simulation that appears complete but hides a dependency.
Cross-surface inconsistencies
The builder, integrations, approvals, and runs pages can show different slices of the same draft. If one reports a more mature state than another, retain the least mature interpretation. Capture the draft, route, connection state, simulation result, and evidence reference so the product team can reproduce the mismatch.
Security-sensitive failures
Stop when the problem involves credential exposure, unexpected app identity, a missing approval, an untrusted MCP output, or an unspecified webhook contract. Do not paste secrets into logs or support messages. Security review is part of the resolution, not an obstacle to be bypassed.
What success looks like
For the current preview, successful troubleshooting ends with a coherent draft and an explainable simulation result. It may also end with a precise statement that a route, connection, schedule, webhook, MCP server, or approval decision is unavailable. That is a complete diagnosis even though the workflow cannot execute.
App-source inspection
When discovery behavior changes between sessions, inspect whether the production CSV or fixture fallback was loaded. A fixture can make an app or pairing disappear without indicating a connector regression. Record the source mode with the draft so another reviewer can reproduce the result.
Generated connector problems
A generated connector can be present for review while canExecute remains false. If the draft expects that connector, inspect its review state and route metadata. Do not treat missing live behavior as a credential error, and do not enable it through undocumented code or configuration.
Webhook and MCP confusion
A webhook/API tab or MCP tab can make an integration look available. Confirm whether there is a real endpoint, server, registry, or tool discovery result. The current product does not provide live webhook or MCP behavior. A blocked result is therefore expected, not a transient outage.
Preview-record mismatch
If the runs page shows a different route or status from the builder, compare the underlying draft and simulation time. The record may describe an older definition or fixture state. Do not revise history to match the current builder; keep both interpretations and flag the inconsistency.
Repeated simulation without changes
Running the same preview repeatedly will not repair missing credentials, disabled routes, policy blocks, or unavailable schedules. Change the relevant prerequisite or stop. Repetition is appropriate only when the underlying draft, connection, or product state has changed.
Support packet
A concise support packet can contain the workflow description, affected step, loaded-source mode, route status, execution route, connection state, approval state, simulation result, and evidence identifier. Remove secrets and real payload data. This is the only broad escalation checklist in the Workflow Agent section; other pages should refer to their specific problem domain.
Distinguish a product limit from a defect
No schedule route, disabled approval controls, an empty MCP registry, and blocked live activation are documented limits. Treat them as defects only when the product claims a supported preview behavior and fails to provide it. This distinction keeps issue reports precise.
Preserve the first failing state
When several warnings appear, begin with the earliest gate in the workflow. Fixing a later connection does not help when the draft itself is invalid. Likewise, a clean draft cannot override an unavailable execution route. Move through definition, route, connection, approval, and simulation in order.
Close the investigation
Record whether the outcome was corrected, remained blocked by design, or requires implementation review. Do not mark a preview as successful merely because no exception was shown. Success means the supported draft-and-simulation objective was achieved and its limitations are explicit.
Simulation evidence review
A simulation result should identify the step and gate that produced the outcome. If it contains only a generic status, compare it with the builder and evidence store. Do not infer a provider failure from a route or policy block.
Fixture-related false alarms
Example recent items, accounts, connectors, or runs can look like user data. Confirm whether they came from seeds or fixtures before investigating them as unexpected production records. Seeded content should never be described as durable history.
Resolve one domain at a time
After correcting a draft issue, validate before changing connections. After correcting a connection, simulate before revising approvals. This order keeps each new result attributable to one change and reduces repeated edits that obscure the original problem.
Documentation correction
If a UI label differs from these docs while the underlying state is clear, retain the canonical backend term and flag the label for review. If the state itself differs, keep the more restrictive interpretation until the implementation sources are reconciled.
Avoid category drift
A missing app is a discovery issue, not automatically a connection issue. A disabled approval action is a preview limitation, not a permissions error. A route marked coming soon is an availability limit, not a simulation defect. Assigning the correct category keeps remediation grounded.
Final verification
Before closing a corrected issue, create one new simulation and compare it with the changed draft. If the product still reports a blocked live path, describe the draft as validated for preview only.
Current conclusion
Close troubleshooting only after the draft’s current boundary is unambiguous. “Preview works; live path unavailable” is a valid resolved outcome when the product intentionally blocks execution.