Skip to main content

Debug failed Shuttle or n8n workflow

Use this page when a Shuttle or n8n workflow did not start, did not complete, or finished without producing the downstream evidence that should have followed.

When to use this page​

  • A workflow failed to trigger.
  • A workflow started but did not complete.
  • A workflow completed but expected downstream sync, message, or task evidence is missing.

Prerequisites​

  • You can capture the workflow identifier and, when present, the execution identifier.
  • You can compare Shuttle-local evidence with downstream Fabric-side evidence when needed.

Architecture / Flow​

Step-by-step procedure​

1. Classify where the workflow failed​

Decide whether the problem is:

  • trigger did not happen
  • execution did not complete
  • downstream evidence never appeared

2. Capture the workflow evidence set​

Record:

  • workflow identifier
  • execution identifier when present
  • last known event or message boundary
  • whether the last successful run was recent or the issue is longstanding

3. Decide whether the boundary is Shuttle-local or cross-system​

If the failure is isolated to Shuttle or n8n, stay in the Shuttle owner path first.

If the workflow completed but expected downstream evidence is missing, compare the Shuttle-to-Fabric boundary and related sync verification.

4. Prefer observation and readback before rerun​

Start with canonical owner verification and workflow readback commands. Re-run or retry only after the failed boundary is understood.

5. Verify the expected downstream effect​

After a bounded fix, confirm:

  • the workflow reaches its expected step
  • and the downstream evidence that was missing now appears

Verification​

This runbook is being used correctly when:

  1. the workflow failure phase is classified before rerun
  2. Shuttle-local and cross-system boundaries are separated
  3. the fix is validated by both execution behavior and downstream evidence

Common failure modes​

Treating every workflow failure as a trigger issue​

Problem:

  • execution and downstream-evidence failures get misdiagnosed.

Better path:

  • classify trigger, execution, and downstream evidence separately

Rerunning without checking whether the downstream handoff failed​

Problem:

  • the same workflow reruns while the real boundary issue stays untouched.

Better path:

  • compare Shuttle-local evidence with Shuttle-to-Fabric evidence first

Source Truth​

  • contracts/docs/public_manufacturer_docs_post_v1_runbooks_v1.json
  • JaddaHelpifyr/jhf-shuttle:docs/TROUBLESHOOTING.md
  • JaddaHelpifyr/jhf-shuttle:docs/OPERATIONS.md
  • JaddaHelpifyr/helpifyr-fabric:docs/operations/N8N_OPERATOR_SYNC_VERIFICATION.md

Next paths​