# Run and Troubleshoot Workflows (https://www.shipfox.io/docs/how-to/run-and-troubleshoot)

Description: Inspect runs, compare attempts, and fix sync, event, log, or runner problems.

Start with the task or visible problem. Each guide tells you which run, event,
workflow, or runner access you need.

## Test before you push [#test-before-you-push]

### [Validate unpushed YAML](https://www.shipfox.io/docs/how-to/run-and-troubleshoot/validate-local-workflow-change)

Check unpushed YAML and trigger eligibility without starting a run.

### [Run unpushed YAML](https://www.shipfox.io/docs/how-to/run-and-troubleshoot/test-local-workflow-change)

Replay validated YAML against a retained event and inspect the result.

## Diagnose a problem [#diagnose-a-problem]

### [Debug a run with an agent](https://www.shipfox.io/docs/how-to/run-and-troubleshoot/debug-failed-run)

Have a coding agent trace a failed run or an event that did not start one.

### [A run didn't complete](https://www.shipfox.io/docs/how-to/run-and-troubleshoot/inspect-runs-and-attempts)

Follow the job graph and compare executions or attempts.

### [Logs are missing](https://www.shipfox.io/docs/how-to/run-and-troubleshoot/inspect-logs)

Read command output, agent sessions, and truncated streams.

### [An agent step fails](https://www.shipfox.io/docs/how-to/run-and-troubleshoot/agent-provider-failures)

Repair provider, model, tool, integration connection, or runtime errors.

### [An event didn't start a run](https://www.shipfox.io/docs/how-to/run-and-troubleshoot/event-routing)

Find why a delivered event did not create a run.

### [A workflow didn't sync](https://www.shipfox.io/docs/how-to/run-and-troubleshoot/workflow-sync)

Find why repository YAML did not produce a usable definition.

### [A job stays pending](https://www.shipfox.io/docs/how-to/author-workflows/choose-runners#resolve-a-pending-job)

Match a pending job with an online runner.