---
title: "Troubleshooting"
html_title: "Enroll Troubleshooting"
description: "Common Enroll errors and what they mean: unsafe PATH, sudo, SSH key passphrases, SOPS, validation, and Ansible runs."
---
<header class="py-5 hero">
  <div class="container py-3">
    <div class="kicker mb-3"><i class="bi bi-tools"></i> Troubleshooting</div>
    <h1 class="display-6 fw-bold mb-2">Common messages and fixes</h1>
    <p class="lead mb-0">Most Enroll failures are deliberate fail-closed checks. This page explains what to do next.</p>
  </div>
</header>

<main class="py-5">
  <div class="container">
    <div class="accordion" id="troubleshootingAccordion">
      <div class="accordion-item"><h2 class="accordion-header"><button class="accordion-button" type="button" data-bs-toggle="collapse" data-bs-target="#t1">“remote sudo requires a password”</button></h2><div id="t1" class="accordion-collapse collapse show" data-bs-parent="#troubleshootingAccordion"><div class="accordion-body"><p>Re-run the remote harvest with <code>-K</code> or <code>--ask-become-pass</code>. Use <code>--no-sudo</code> only when you accept a limited harvest.</p><pre class="terminal"><code>enroll harvest --remote-host app01.example.net --remote-user mig -K --out ./harvest</code></pre></div></div></div>
      <div class="accordion-item"><h2 class="accordion-header"><button class="accordion-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#t2">“SSH private key passphrase is required”</button></h2><div id="t2" class="accordion-collapse collapse" data-bs-parent="#troubleshootingAccordion"><div class="accordion-body"><p>Use <code>--ask-key-passphrase</code> interactively or <code>--ssh-key-passphrase-env ENV_VAR</code> in CI.</p><pre class="terminal"><code>export ENROLL_SSH_KEY_PASSPHRASE='...'
enroll harvest --remote-host app01 --ssh-key-passphrase-env ENROLL_SSH_KEY_PASSPHRASE --out ./harvest</code></pre></div></div></div>
      <div class="accordion-item"><h2 class="accordion-header"><button class="accordion-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#t3">Unsafe root <code>PATH</code> warning</button></h2><div id="t3" class="accordion-collapse collapse" data-bs-parent="#troubleshootingAccordion"><div class="accordion-body"><p>When running as root, Enroll refuses or prompts if <code>PATH</code> could resolve host tools from an attacker-controlled location. Fix the PATH or parent directory permissions before running in automation. Use <code>--assume-safe-path</code> only when you intentionally trust the environment.</p></div></div></div>
      <div class="accordion-item"><h2 class="accordion-header"><button class="accordion-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#t4">“Harvest path is not a directory” during manifest</button></h2><div id="t4" class="accordion-collapse collapse" data-bs-parent="#troubleshootingAccordion"><div class="accordion-body"><p>Plain manifest mode expects a directory harvest. For an encrypted harvest tarball, pass <code>--sops &lt;fingerprint&gt;</code> to manifest so Enroll decrypts and extracts it safely before rendering.</p><pre class="terminal"><code>enroll manifest --harvest ./harvest/harvest.tar.gz.sops --out ./ansible --sops &lt;GPG_FINGERPRINT&gt;</code></pre></div></div></div>
      <div class="accordion-item"><h2 class="accordion-header"><button class="accordion-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#t5">Validation errors about missing or orphaned artifacts</button></h2><div id="t5" class="accordion-collapse collapse" data-bs-parent="#troubleshootingAccordion"><div class="accordion-body"><p>The bundle is internally inconsistent: <code>state.json</code> references an artifact that is absent, or <code>artifacts/</code> contains files not referenced by state. Re-harvest from a trusted host, or inspect the bundle provenance before using it.</p></div></div></div>
      <div class="accordion-item"><h2 class="accordion-header"><button class="accordion-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#t6">Generated Ansible says a collection/module is missing</button></h2><div id="t6" class="accordion-collapse collapse" data-bs-parent="#troubleshootingAccordion"><div class="accordion-body"><p>Install the generated requirements before running the playbook. Container, Podman, Flatpak, or Snap roles may add collection requirements.</p><pre class="terminal"><code>cd ./ansible
ansible-galaxy collection install -r requirements.yml</code></pre></div></div></div>
      <div class="accordion-item"><h2 class="accordion-header"><button class="accordion-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#t7">Expected shell dotfiles were not captured</button></h2><div id="t7" class="accordion-collapse collapse" data-bs-parent="#troubleshootingAccordion"><div class="accordion-body"><p>Automatic capture of <code>.bashrc</code>, <code>.profile</code>, <code>.bash_logout</code>, and <code>.bash_aliases</code> is disabled unless <code>--dangerous</code> is used. Prefer targeted <code>--include-path</code> first; normal secret checks still apply.</p></div></div></div>
    </div>
  </div>
</main>