Troubleshooting

📘

Running v1?

This page covers Manifest Self-Hosted 2.x. For installations from the v1 installer generation, see Troubleshooting v1.

Installer Logs

Every manifest-installer command writes a timestamped run log, installer-<timestamp>.log, under the state directory's log/ folder: ~/.local/state/manifest/log/ (or $XDG_STATE_HOME/manifest/log). Running as root (for example under sudo) uses that account's home, such as /root/.local/state/manifest/log/. One file maps to one command run, and each run log always records full debug-level detail even when the console showed less, so it is the first place to look when a step fails. The installer keeps the 10 most recent run logs and prunes older ones automatically.

Common Issues

Another Command Is Already Running

Symptom: a command fails because another manifest-installer command is running.

The installer takes a per-host lock so concurrent invocations can't corrupt state.

Solution: wait for the other command to finish, then re-run.

deploy Stops Immediately, Pointing at a Missing Step

deploy never auto-runs download or setup.

Solution: if it reports no downloaded versions, run manifest-installer download; if it reports no deployment config, run manifest-installer setup.

deploy Refuses a Package Flavor

Symptom: deploy stops before touching the host because the downloaded packages were built for the other FIPS setting than config.yaml has.

Solution: either download the matching set (manifest-installer download --version <x.x.x> --flavor fips, or --flavor default), removing the existing ~/.local/share/manifest/versions/<x.x.x>/ directory first, or re-run setup and change the FIPS answer. For an air-gapped install, rebuild the bundle on the prep host with the matching --flavor on both download and export-bundle, remove ~/.local/share/manifest/versions/<x.x.x>/ on the target, and import again.

download Refuses to Switch Flavor

A version directory holds one flavor.

Solution: remove ~/.local/share/manifest/versions/<x.x.x>/ and re-run download with the flavor you need.

download Was Interrupted

Solution: re-run the same command. Packages already on disk are skipped, so the download resumes where it stopped; once a version is complete, a re-run confirms already downloaded in seconds.

Cannot Pull Packages from ECR

Symptom: manifest-installer download fails pulling from Manifest's registry.

Solution: verify the credentials Manifest issued have not expired, then re-set them:

manifest-installer config set aws.accessKeyID <new-access-key-id>
read -rs SECRET_ACCESS_KEY   # paste the new secret access key; input is not echoed
printf %s "$SECRET_ACCESS_KEY" | manifest-installer config set aws.secretAccessKey

Or export AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY / AWS_REGION for a one-off run; environment variables override the persisted values.

Disk Space Errors During download

Platform packages are large.

Solution: ensure the host meets the storage requirements in Requirements. To put downloaded packages on a different volume, export XDG_DATA_HOME before running the CLI.

deploy Fails Partway Through

Solution: re-running deploy is safe. Every step — host prep, k3s install, registry bootstrap, platform deploy — is idempotent and skips work already done, so a re-run converges to the failed point in seconds. There is no state to manually clean up between attempts.

Kernel-Module Load Failures

Symptom: deploy reports failures loading br_netfilter or overlay.

Some hardened kernels block these modules until specifically allowed.

Solution: confirm the modules are available on your distribution, then re-run deploy.

Ports Already in Use

k3s requires 6443; the Zarf registry requires 31999; Traefik requires 80/443.

Solution: if something else on the host owns these ports, stop it before running deploy.

Support

For additional assistance, contact Manifest Cyber support:

• Email: [email protected]

Related Documentation

• Requirements - Host and network requirements
• Installation - Installation process
• Configuration Reference - Configuration options