# 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 ``` 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 --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:" ``` Safe fix: use `backend: local` or `backend: ssh` for executable workflows. S3 config shape is accepted only for validation; runtime execution is unavailable. ## `backend s3 is not implemented for execution` Likely cause: the config validates but `run` tried to execute S3, which is not implemented. Diagnostic: ```sh go run ./cmd/distributor run --config --dry-run ``` Safe fix: use `local` or `ssh` for executable workflows. See [configuration](config.md). ## `host is required for ssh backend` Likely cause: SSH config is missing the structured `host` field, or an old URI-based SSH config is still in use. Diagnostic: ```sh go run ./cmd/distributor run --config --dry-run ``` Safe fix: configure SSH with `host`, optional `user` and `port`, and `path`. The `uri` field is not used for SSH execution. ## `no SSH auth methods configured` Likely cause: neither an SSH agent nor `ssh_key_file` is available. Diagnostic: ```sh test -n "$SSH_AUTH_SOCK" && ssh-add -l ls -l ``` Safe fix: start an SSH agent with an appropriate key loaded, or configure `ssh_key_file` with a readable private key. ## `host key ... is unknown` or `known_hosts is required` Likely cause: strict host key checking has no known host key, or `accept-new` cannot persist a new key. Diagnostic: ```sh ls -l ssh-keygen -F -f ``` Safe fix: configure a writable `known_hosts` path for `accept-new`, pre-populate `known_hosts` for `strict`, or explicitly use `host_key_policy: off` only for insecure test environments. ## `host key ... has changed` Likely cause: the remote server presented a different host key than the one recorded in `known_hosts`. Diagnostic: ```sh ssh-keygen -F -f ``` Safe fix: verify the server identity out of band before updating `known_hosts`. Do not switch to `host_key_policy: off` to bypass an unexpected changed key. ## `stat ssh ... not_found` or `no bundles found` Likely cause: the configured SSH `path` is wrong, unreadable, or does not contain source bundles. Diagnostic: ```sh sftp @ ``` Safe fix: correct the remote root `path`, permissions, or source bundle location. ## `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 -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 ``` 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 -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 /.distributor.json go run ./cmd/distributor inspect ``` 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 --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 -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).