Stop your Ansible local facts from ghosting your automation scripts
By Saket Jain Published Linux/Unix
Stop your Ansible local facts from ghosting your automation scripts
Technical Briefing | 11/16/2026
You spend hours crafting the perfect Ansible role, only to realize the setup tasks aren’t triggering because your custom fact scripts are behaving differently across your fleet. Most engineers drop a shell script in /etc/ansible/facts.d/ and assume it will just work, but if that script hits a non-zero exit code or hits a timeout, Ansible just ignores the entire file silently. This bit me in prod when a stale NFS mount caused our hardware discovery script to hang, effectively making our infrastructure ‘invisible’ to our own deployment playbooks.
Why silent failures are the default
Ansible gathers facts by executing every executable file in that directory. If your script outputs anything other than clean JSON to stdout, or if it errors out without providing a fallback, the Ansible fact-gathering task just moves on. You don’t get a warning, you don’t get an error, you just get a variable that doesn’t exist when you try to use it in a conditional. It is infuriatingly quiet.
ansible all -m setup -a 'filter=ansible_local'
- Ensure your script output is valid JSON by piping it through jq
- Add a shebang line so Ansible doesn’t guess the interpreter
- Redirect stderr to /dev/null so noise doesn’t corrupt the JSON stream
- Set an explicit timeout in your wrapper if you are querying network resources
Debugging the output before the play runs
Stop relying on the playbook to tell you why your custom facts are failing. Log into the node, drop into /etc/ansible/facts.d/ and run your scripts manually. If they don’t output perfect JSON, your playbook is never going to see them. I always add a cron job that checks the syntax of my fact scripts every morning; it is a cheap insurance policy that saves you from those Friday afternoon deployment disasters.
Next time you add a new piece of hardware metadata, take five extra minutes to wrap your script in a error-handler that outputs a static JSON block on failure. Knowing exactly why your infrastructure isn’t reporting back is better than staring at an empty variable and guessing which node is the outlier.
