4.3 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 for executable workflows. SSH and S3 config shapes are accepted only for validation; runtime execution is not implemented.
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:
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 until those adapters exist. See configuration.
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.