--- title: "Troubleshooting" html_title: "Enroll Troubleshooting" description: "Common Enroll errors and fixes for generated Ansible, Puppet, and Salt manifests." ---
Troubleshooting

Common errors and how to fix them

Most first-run problems are either missing runtime tools, old Ansible community collections, or files that Enroll intentionally skipped for safety.

Ansible collections Podman platform error Flatpak from_url error JinjaTurtle Missing files Harvest output parent Validate artifacts Remote harvest Diff enforcement

Start here for Ansible module errors

Generated Ansible manifests may use community collections when a harvest contains Docker/Podman images, Flatpaks, or Snaps. Enroll writes a requirements.yml beside playbook.yml, and the generated manifest README.md shows the install command.

$ cd /path/to/generated/ansible-manifest
$ ansible-galaxy collection install -r requirements.yml

Run this in the same Python virtualenv, container, CI job, or user account that will run ansible-playbook. If an older collection is already installed and Ansible keeps finding it first, retry with --force or adjust ANSIBLE_COLLECTIONS_PATH.

Podman error: unsupported platform parameter

If the host has an older containers.podman / community.podman Galaxy collection, an Ansible run may fail with a message like this:

[ERROR]: Task failed: Module failed: Unsupported parameters for (containers.podman.podman_image) module: platform. Supported parameters include: arch, auth_file, build, ca_cert_dir, executable, force, name, password, path, pull, pull_extra_args, push, push_args, quadlet_dir, quadlet_file_mode, quadlet_filename, quadlet_options, state, tag, username, validate_certs (authfile, build_args, buildargs, tls_verify, tlsverify).
Cause

The generated task is using a newer module interface than the collection currently installed on the machine running Ansible.

Fix

Install the collection versions constrained by the generated manifest:

$ cd /path/to/generated/ansible-manifest
$ ansible-galaxy collection install -r requirements.yml

Then re-run the playbook from the same environment. If Ansible still reports the older module, check ansible-galaxy collection list and remove or override the stale collection path.

Flatpak error: unsupported from_url parameter

Flatpak tasks can fail in the same way when the installed community.general collection is too old for the generated role.

Fix

Use the generated Ansible requirements file before applying the manifest:

$ cd /path/to/generated/ansible-manifest
$ ansible-galaxy collection install -r requirements.yml

The same advice applies when Snap, Docker, Podman, or Flatpak roles complain about unknown module parameters: install from requirements.yml first, because Enroll generated that file for the manifest it just wrote.

Salt error: Failed to import utils pycrypto

You run the salt-call command and see an error Failed to import utils pycrypto, this is due most likely to a syntax error with a Traceback that includes AttributeError: module 'crypt' has no attribute 'methods'.

Fix

It's not an Enroll bug. Upgrade to Salt Stack 3008.1, in their Debian packages they use Python 3.14 and have solved the problem. The problem occurs with older Python, and is described in this upstream bug report.

JinjaTurtle is not found, or template generation was skipped

When --jinjaturtle auto is used, Enroll only templates recognised config files if the jinjaturtle executable is available on PATH. If it is missing, Enroll safely falls back to copying raw files. When --jinjaturtle on is used, missing JinjaTurtle is a hard error.

Make templating optional (this is the default already)
$ enroll manifest --harvest ./harvest --target ansible --out ./ansible --jinjaturtle auto
Disable templating entirely
$ enroll manifest --harvest ./harvest --target puppet --out ./puppet --jinjaturtle off # or --no-jinjaturtle

If a generated template would reference missing variables, Enroll should fall back to a raw file copy rather than producing a broken manifest.

A file I expected was not harvested

The default harvest is intentionally conservative. A file may be skipped because it matched an exclude pattern, looked sensitive, looked binary, was too large, was already captured by another role, or was outside Enroll's standard scan paths.

Explicitly include a path
$ enroll harvest --out ./harvest --include-path /opt/myapp/config.yml
Inspect what happened
$ enroll explain ./harvest
$ enroll validate ./harvest
Be careful with --dangerous
Use --dangerous only when you understand that it can harvest secrets such as private keys, tokens, credentials, and application config containing passwords.

Error: harvest output parent is owned by the wrong user

When Enroll is run as root, it deliberately refuses to create a harvest below a parent directory that is controlled by a non-root user. This is a safety check: a user-owned parent directory can be renamed or replaced while a root process is writing files, which can become a symlink or path-race problem.

error: harvest output parent is not owned by root; refusing root-run output: /home/alice
error: harvest output parent is not owned by root; refusing root-run output: /tmp/tmp.abcd1234
What Enroll is protecting you from

Harvest output can contain detailed system state and, when --dangerous is used, may contain sensitive configuration material. If Enroll is running as root, it needs the output path to stay exactly where it was checked. Refusing user-owned parent directories helps avoid accidental writes through symlinks or paths that can be swapped underneath the process.

Use a root-owned output area

Create a dedicated root-owned directory and place harvests underneath it:

$ sudo install -d -m 700 -o root -g root /var/tmp/enroll
$ sudo enroll harvest --out /var/tmp/enroll/host1
/tmp itself is okay

A fresh output directory directly under the normal root-owned sticky /tmp directory is accepted. The output path must not already exist.

$ sudo enroll harvest --out /tmp/host1-harvest
Avoid root harvests into your home directory
A command such as sudo enroll harvest --out ~/harvest may expand to a path below a user-owned home directory. Use /var/tmp/enroll, /root, or a fresh directory directly under /tmp instead.
Remote harvest note

In normal remote mode, Enroll uses sudo on the remote host so it can collect system-level state. Recent Enroll versions create a separate root-owned temporary directory for the remote bundle. If an older version reports this error for a path like /tmp/tmp.xxxxx during remote harvest, upgrade Enroll. Use --no-sudo only when you intentionally want a limited, non-root harvest.

Generated manifest references a missing artifact

If a manifest task points at a missing source file, validate the original harvest first. Validation checks state.json, referenced artifacts, generated firewall/sysctl files, and unreferenced artifact warnings.

$ enroll validate /path/to/harvest

If validation passes, check whether you moved, edited, or partially copied the generated manifest after rendering it.

Remote harvest cannot sudo or cannot unlock an SSH key

Remote mode can prompt for sudo and private-key passphrases, but CI and non-interactive shells should pass the required information up front. You can set the ENROLL_SSH_KEY_PASSPHRASE environment variable if needed, and then pass --ssh-key-passphrase-env ENROLL_SSH_KEY_PASSPHRASE.

Prompt for sudo
$ enroll harvest --remote-host host.example.net --ask-become-pass --out ./harvest
Prompt for encrypted SSH key
$ enroll harvest --remote-host host.example.net --ask-key-passphrase --out ./harvest

If host key verification fails, connect with normal ssh first so the expected key is in known_hosts, or use your normal SSH config with Enroll's remote SSH config support.

enroll diff --enforce did not change everything

Enforcement is best-effort drift correction from the old harvest. It is intentionally conservative and does not try to do risky things such as arbitrary package downgrades.

Choose the enforcement target explicitly

By default, enforcement uses Ansible. You can choose Puppet or Salt when those tools are available on the host running enforcement:

$ enroll diff --old ./golden --new ./current --enforce --target ansible
$ enroll diff --old ./golden --new ./current --enforce --target puppet
$ enroll diff --old ./golden --new ./current --enforce --target salt

For non-Ansible targets, make sure puppet or salt-call is installed and on PATH before running enforcement.

Error about schema when validating or manifesting a harvest

You see an error like error: harvest state does not match this Enroll version's schema; please re-harvest the host with this version of Enroll.

Reharvest the host

The harvest has either been tampered with, become corrupt, or was made with an earlier version of Enroll, which means its layout is a different structure than what Enroll now expects.

The best thing to do is run the harvest again. Enroll will validate the harvest against the latest schema when you go to manifest it.

If you still experience the error, please report it as a bug!