Ansible troubleshooting - fatal template error while templating string

How to reproduce, troubleshoot, and fix the "FATAL template error while templating string" Ansible runtime error.

December 17, 2023

Access the Complete Video Course and Learn Quick Ansible by 200+ Practical Lessons

#ansible #troubleshooting #error #fatal #ansible-template #automation #ansible-playbook-tutorial #ansible-modules #ansible-101 #ansible-automation #ansible-for-beginners #open-source #ansible-tutorial #ansible-tutorial-for-beginners #devops-engineer #devops-tutorial-for-beginners #learn-ansible #ansible-roles #information-technology #ansible-playbook #ansible-guide #ansible-beginner #ansible-templating-error #ansible-templating-sting #linux

Introduction

Welcome to another episode of Ansible Pilot! I’m Luca Berton, and today we’ll be diving into Ansible troubleshooting, focusing on the “FATAL template error while templating string” runtime error. Join me as we explore how to reproduce, troubleshoot, and fix this challenging issue.

The Demo

Let’s jump straight into a live demo to understand the error practically. In this example, we have a playbook (template_error_string_error.yml) attempting to create an empty file with a variable referencing ~/example.txt.

# template_error_string_error.yml
---
- name: file module demo
  hosts: all
  vars:
    myfile: "{{ ~/example.txt }}"
  tasks:
    - name: Creating an empty file
      ansible.builtin.file:
        path: "{{ myfile }}"
        state: touch

Executing this playbook (ansible-playbook -i inventory template_error_string_error.yml) results in a fatal error:

TASK [Creating an empty file] ***********************************************************************************************************
fatal: [demo.example.com]: FAILED! => {"msg": "An unhandled exception occurred while templating '{{ ~/example.txt }}'. Error was a <class 'ansible.errors.AnsibleError'>, original message: template error while templating string: unexpected '~'. String: {{ ~/example.txt }}"}

Understanding the Error

The error message is clear: “template error while templating string: unexpected ‘~’.” The issue lies in the attempt to use the tilde (~) symbol in the variable, which is not a valid attribute for templating.

The Best Resources For Ansible

Certifications

The Linux Foundation Linux Performance Tuning - Build a broad toolkit to optimize Linux performance from the kernel up

Coursera Pro - Unlimited access to 7,000+ world-class courses, hands-on projects, and job-ready certificate programs—all included in your subscription

Video Course

Udemy: Learn Ansible Automation in 250+examples & practical lessons: Learn Ansible with some real-life examples of how to use the most common modules and Ansible Playbook

Printed Book

eBooks

Fixing the Code

To resolve the issue, we need to correct our playbook. The fixed version (template_error_string_fix.yml) uses the correct variable format:

# template_error_string_fix.yml
---
- name: file module demo
  hosts: all
  vars:
    myfile: "~/example.txt"
  tasks:
    - name: Creating an empty file
      ansible.builtin.file:
        path: "{{ myfile }}"
        state: touch

Executing the fixed playbook (ansible-playbook -i demo/inventory troubleshooting/template_error_string_fix.yml) should now complete without errors:

TASK [Creating an empty file] ***********************************************************************************************************
changed: [demo.example.com]

Recap

In this tutorial, we walked through reproducing, troubleshooting, and fixing the “FATAL template error while templating string” error in Ansible. The key takeaway is to ensure that variables are formatted correctly in your playbooks.

I hope this guide helps you navigate and resolve similar issues in your Ansible automation journey. If you found this information valuable, consider subscribing for more Ansible insights.

demo

The best way of talking about Ansible troubleshooting is to jump in a live demo to show you practically the not a valid attribute for a Play error and how to solve it!

error code

template_error_string_error.yml

---
- name: file module demo
  hosts: all
  vars:
    myfile: "{{ ~/example.txt }}"
  tasks:
    - name: Creating an empty file
      ansible.builtin.file:
        path: "{{ myfile }}"
        state: touch

error execution

output

$ ansible-playbook -i demo/inventory troubleshooting/template_error_string_error.yml
PLAY [file module demo] ****************************************************************************************************************************************************************************
TASK [Gathering Facts] *****************************************************************************************************************************************************************************
ok: [demo.example.com]
TASK [Creating an empty file] **********************************************************************************************************************************************************************
fatal: [demo.example.com]: FAILED! => {"msg": "An unhandled exception occurred while templating '{{ ~/example.txt }}'. Error was a <class 'ansible.errors.AnsibleError'>, original message: template error while templating string: unexpected '~'. String: {{ ~/example.txt }}"}
PLAY RECAP *****************************************************************************************************************************************************************************************
demo.example.com           : ok=1    changed=0    unreachable=0    failed=1    skipped=0    rescued=0    ignored=0

fix code

template_error_string_fix.yml

---
- name: file module demo
  hosts: all
  vars:
    myfile: "~/example.txt"
  tasks:
    - name: Creating an empty file
      ansible.builtin.file:
        path: "{{ myfile }}"
        state: touch

fix execution

output

$ ansible-playbook -i demo/inventory troubleshooting/template_error_string_fix.yml
PLAY [file module demo] ****************************************************************************************************************************************************************************
TASK [Gathering Facts] *****************************************************************************************************************************************************************************
ok: [demo.example.com]
TASK [Creating an empty file] **********************************************************************************************************************************************************************
changed: [demo.example.com]
PLAY RECAP *****************************************************************************************************************************************************************************************
demo.example.com           : ok=2    changed=1    unreachable=0    
failed=0    skipped=0    rescued=0    ignored=0

Recap

Now you know better how to troubleshoot the template error while templating string error. Subscribe to the YouTube channel, Medium, and Website, X (formerly Twitter) to not miss the next episode of the Ansible Pilot.