5.8 KiB
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:
ls -l <config-path>
Safe fix: pass an existing config path with --config, or install a config at the default path. See configuration.
parse config ... field not found
Likely cause: the YAML contains an unknown field. Config loading rejects unknown keys.
Diagnostic:
go run ./cmd/distributor run --config <config-path> --dry-run
Safe fix: compare the file to the reference in configuration 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:
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:
go run ./cmd/distributor run --config <config-path> --dry-run
Safe fix: use local or ssh for executable workflows. See configuration.
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:
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:
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:
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:
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:
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:
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:
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.
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:
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:
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:
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:
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:
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.