# Distributor Troubleshooting

## `load config ... no such file or directory`

Likely cause: `run` could not find the config path. If `--config` is omitted, the default path is `/usr/local/etc/distributor/config.yml`.

Diagnostic:

```sh
ls -l <config-path>
```

Safe fix: pass an existing config path with `--config`, or install a config at the default path. See [configuration](config.md).

## `parse config ... field not found`

Likely cause: the YAML contains an unknown field. Config loading rejects unknown keys.

Diagnostic:

```sh
go run ./cmd/distributor run --config <config-path> --dry-run
```

Safe fix: compare the file to the reference in [configuration](config.md) and remove or rename unsupported fields.

## `validate config ... backend ... is unsupported`

Likely cause: a source or destination uses a backend name other than `local`, `ssh`, or `s3`.

Diagnostic:

```sh
rg -n "backend:" <config-path>
```

Safe fix: use `backend: local` for executable workflows. SSH and S3 config shapes are accepted only for validation; runtime execution is unavailable.

## `backend ssh is not implemented for execution` or `backend s3 is not implemented for execution`

Likely cause: the config validates but `run` tried to execute a remote backend.

Diagnostic:

```sh
go run ./cmd/distributor run --config <config-path> --dry-run
```

Safe fix: use local destinations for current executable workflows, or keep remote backend configs under roadmap material unless those adapters are added. See [configuration](config.md).

## `validate command requires a path` or `inspect command requires a path`

Likely cause: `validate` or `inspect` was run without a path.

Diagnostic:

```sh
go run ./cmd/distributor validate --help
go run ./cmd/distributor inspect --help
```

Safe fix: pass a local source bundle directory or a local tree containing source bundles.

## `no bundles found under "."`

Likely cause: the selected source root does not contain a `manifest.json` source bundle.

Diagnostic:

```sh
find <source-root> -name manifest.json -print
```

Safe fix: point the command or config at the directory containing the source bundle, or write a valid `manifest.json` and listed files. See [CLI](cli.md).

## `sha256 mismatch`, `size mismatch`, or `digest mismatch`

Likely cause: a listed source file changed after `manifest.json` was created, or the manifest digest does not match its file list.

Diagnostic:

```sh
go run ./cmd/distributor validate <source-root>
```

Safe fix: regenerate the producer bundle and manifest together. Do not edit destination state to work around source digest failures.

## `destination has content but no distributor state`

Likely cause: the destination path is not empty and has no `.distributor.json` state file, so `distributor` will not claim it as managed.

Diagnostic:

```sh
find <destination-path> -maxdepth 2 -print
```

Safe fix: choose an empty destination path or move existing files aside after confirming they are not needed. There is no force overwrite option.

## `fail_conflict`

Likely cause: existing `.distributor.json` belongs to a different pipeline, a different destination, a different source id, or a same-created source with a different digest.

Diagnostic:

```sh
cat <destination-path>/.distributor.json
go run ./cmd/distributor inspect <source-root>
```

Safe fix: verify you are publishing the intended source to the intended destination. Use a separate destination path for unrelated content.

## `destination output path collision`

Likely cause: configured publication would write two outputs to the same destination path, such as publishing a source `report.html` while also generating `report.html` from `report.md`.

Diagnostic:

```sh
go run ./cmd/distributor run --config <config-path> --dry-run
```

Safe fix: adjust the source bundle contents or publish policy so source and generated outputs do not collide.

## A run failed after writing some files

Likely cause: a write failed partway through publication. Local execution attempts to clean up outputs written during the failed attempt.

Diagnostic:

```sh
find <destination-path> -maxdepth 2 -print
```

Safe fix: inspect the destination before retrying. If only unrelated unmanaged files remain, move them aside or choose a clean destination. Re-run with `--dry-run` before publishing again. See [operations](operations.md).