# Troubleshoot Shipfox Workflow Sync (https://www.shipfox.io/docs/how-to/run-and-troubleshoot/workflow-sync)

Description: Find why workflow YAML did not produce a usable definition and verify the corrected sync.

Use this guide when a workflow is missing from the Workflows tab. It also applies
when the project reports **Workflow sync failed**.

## Before you begin [#before-you-begin]

You need access to the source integration connection and the repository's
default branch.

## Inspect the sync result [#inspect-the-sync-result]

Open the project and select **Workflows**. Read the sync badge and failure
message before changing the workflow.

| Result                                              | What to check                                                                                                             |
| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| No workflow files                                   | The default branch contains `.yml` or `.yaml` files under `.shipfox/workflows/`                                           |
| Invalid definition                                  | The named file follows the strict workflow schema and every referenced job, step, integration connection, and tool exists |
| Repository or file not found                        | The project still points to a repository visible through its source integration connection                                |
| Access denied or integration connection unavailable | The source integration is installed and authorized for the repository                                                     |
| Too large or too many files                         | The workflow files fit the documented [limits](https://www.shipfox.io/docs/reference/limits)                                                         |
| Context not available                               | A field reads a context that does not exist where Shipfox fills that field. See below                                     |

## Correct a context that is not available [#correct-a-context-that-is-not-available]

A field can read only the contexts listed in [Context
availability](https://www.shipfox.io/docs/reference/contexts#context-availability). If it reads another
context, sync fails. The error names the field, the unavailable context, and the
stage where that context first exists:

```text
Job runner interpolation references context "steps" that is not available at
job activation. "steps" becomes available at step dispatch.
```

Correct it in one of two ways:

* Move the reference to a field that Shipfox fills later. A step `run` or `env`
  value can read step results that `jobs.<job_id>.runner` cannot.
* Carry the value forward as data. Declare a step output or a job output, then
  read it through `steps`, `needs`, or `jobs` in the later field.

## Correct and verify [#correct-and-verify]

1. Fix the reported problem on the repository's default branch.
2. Commit and push the correction.
3. Return to the Workflows tab.
4. Wait for the sync badge to reach **succeeded**.
5. Open the workflow and confirm that its source matches the committed YAML.

A successful sync changes only future runs. It does not change an active run. It
also leaves earlier attempts unchanged.