Common Enroll problems and fixes

Root run refuses to continue because PATH is unsafe

When running as root, Enroll refuses non-interactive execution if PATH contains ., an empty entry, a relative entry, a non-root-owned directory, or group/world-writable directories/parents that could let an untrusted binary be executed.

$ export PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
$ enroll harvest --out ./harvest

# only for trusted CI environments where the PATH is intentional
$ enroll harvest --out ./harvest --assume-safe-path

Ansible complains about missing modules or unsupported parameters

Generated roles can use collections for Docker, Podman, Flatpak, Snap, or other resources. Install the generated requirements from the manifest output directory before running the playbook.

$ cd /tmp/enroll-ansible
$ ansible-galaxy collection install -r requirements.yml
$ ansible-galaxy collection list

If Ansible still uses an older collection, check your configured collection paths and remove or override stale copies.

JinjaTurtle is missing or template generation was skipped

By default, Enroll uses JinjaTurtle if the jinjaturtle executable exists on PATH; otherwise it safely copies raw files. --jinjaturtle makes missing JinjaTurtle a hard error, and --no-jinjaturtle disables templating entirely.

$ enroll manifest --harvest ./harvest --out ./ansible --jinjaturtle

$ enroll manifest --harvest ./harvest --out ./ansible --no-jinjaturtle

A file I expected was not harvested

Default harvesting is conservative. A file may be skipped because it matched an exclude pattern, looked sensitive, looked binary, was too large, was already captured elsewhere, was unreadable, or was outside standard scan paths.

$ enroll harvest --out ./harvest --include-path /opt/myapp/config.yml

$ enroll explain ./harvest
$ enroll validate ./harvest

Validation fails, or a manifest references a missing artifact

Validate the original harvest. Validation checks the schema, referenced artifacts, artifact safety, and unreferenced artifact warnings.

$ enroll validate /path/to/harvest
$ enroll validate /path/to/harvest --format json --out validate.json
$ enroll validate /path/to/harvest --fail-on-warnings

If validation passes but Ansible cannot find a file, check whether the generated output was partially copied, edited, or moved after rendering.

Remote harvest cannot sudo or cannot unlock an SSH key

Remote mode can prompt for sudo and private-key passphrases. In non-interactive shells, provide the required inputs explicitly.

$ enroll harvest --remote-host host.example.net --ask-become-pass --out ./harvest

$ enroll harvest --remote-host host.example.net --ask-key-passphrase --out ./harvest

$ export ENROLL_SSH_KEY_PASSPHRASE='...'
$ enroll harvest --remote-host host.example.net --ssh-key-passphrase-env ENROLL_SSH_KEY_PASSPHRASE --out ./harvest

If host key verification fails, connect with normal ssh first so the expected key is in known_hosts, or use --remote-ssh-config.

I have a SOPS manifest bundle. How do I run it?

manifest --sops produces one encrypted manifest.tar.gz.sops file. It is an at-rest storage format, not something Ansible runs directly. Decrypt and extract it first.

$ cd /path/to/output
$ sops -d manifest.tar.gz.sops | tar -xzvf -
$ cd manifest
$ ansible-galaxy collection install -r requirements.yml
$ ansible-playbook -i "localhost," -c local playbook.yml --check