198 lines
5.8 KiB
Markdown
198 lines
5.8 KiB
Markdown
# 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` 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 <config-path> --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 <config-path> --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 <ssh-key-file>
|
|
```
|
|
|
|
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 <known-hosts-path>
|
|
ssh-keygen -F <host> -f <known-hosts-path>
|
|
```
|
|
|
|
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 <host> -f <known-hosts-path>
|
|
```
|
|
|
|
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 <user>@<host>
|
|
```
|
|
|
|
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 <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).
|