---
title: "Template Troubleshooting"
description: "Fix common TurboDocx template issues: broken variables, formatting problems, unsupported image formats and placeholder errors, with video walkthroughs."
url: "https://docs.turbodocx.com/docs/TurboDocx-Templating/Template-Troubleshooting"
---

# Template Troubleshooting

> Fix common TurboDocx template issues: broken variables, formatting problems, unsupported image formats and placeholder errors, with video walkthroughs.

Before you throw your computer, watch this video! Your variables aren't broken, but your template might need a little bit of tender loving care. Here are the most common issues and how to fix them.

## Video Tutorial

  <iframe 
    src="https://www.youtube.com/embed/oTN2c3Y9X-Y?si=GdDa2PSFfFMvEQPu" 
    title="YouTube video player" 
    frameborder="0" 
    allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" 
    referrerpolicy="strict-origin-when-cross-origin" 
    allowfullscreen
    style={{position: 'absolute', top: 0, left: 0, width: '100%', height: '100%'}}
  ></iframe>

## Common Variable Issues

### 1. Variable Naming Rules

All variables must be **one word only** - no spaces allowed inside the `{brackets}`.

    ✅
    Correct - One word only

    <code style={{backgroundColor: '#dcfce7', padding: '4px 8px', borderRadius: '4px', marginRight: '12px', color: '#166534'}}>{'{CustomerName}'}</code>
    <code style={{backgroundColor: '#dcfce7', padding: '4px 8px', borderRadius: '4px', marginRight: '12px', color: '#166534'}}>{'{ProjectDate}'}</code>
    <code style={{backgroundColor: '#dcfce7', padding: '4px 8px', borderRadius: '4px', color: '#166534'}}>{'{ScopeSection}'}</code>

    ✨ These variable names will work perfectly in your templates

    ❌
    Incorrect - Contains spaces

    <code style={{backgroundColor: '#fee2e2', padding: '4px 8px', borderRadius: '4px', marginRight: '12px', color: '#991b1b', textDecoration: 'line-through'}}>{'{Customer Name}'}</code>
    <code style={{backgroundColor: '#fee2e2', padding: '4px 8px', borderRadius: '4px', marginRight: '12px', color: '#991b1b', textDecoration: 'line-through'}}>{'{Project Date}'}</code>
    <code style={{backgroundColor: '#fee2e2', padding: '4px 8px', borderRadius: '4px', color: '#991b1b', textDecoration: 'line-through'}}>{'{Scope Section}'}</code>

    ⚠️ Spaces inside brackets will prevent variables from being recognized

:::tip Naming Best Practices
- Use **CamelCase** for multi-word variables: `{CustomerName}` instead of `{Customer Name}`
- Keep names **descriptive but concise**: `{ProjectStartDate}` instead of `{Date}`
- Be **consistent** across your templates: always use the same format
:::

### 2. Variables Must Be On Their Own Line

**Critical Rule:** When inserting sections, images, or rich text, the variable needs to be on its own line. Don't squeeze it into a sentence.

#### Examples: How to Format Variables Correctly

    ❌
    Incorrect - Variable mixed with other text

      Rich Text/Section Variables:
      <code style={{backgroundColor: '#f3f4f6', padding: '2px 4px', borderRadius: '3px'}}>Proposal Section: {'{ProposalSection}'}, If you have any questions about the proposal...</code>

      Image Variables:
      <code style={{backgroundColor: '#f3f4f6', padding: '2px 4px', borderRadius: '3px'}}>Photo: {'{HeadshotImage}'}, Nicolas Fry, CEO</code>

    ⚠️ This format will prevent variables from working properly

    ✅
    Correct - Variable on its own line

      Rich Text/Section Variables:
      <code style={{backgroundColor: '#f3f4f6', padding: '2px 4px', borderRadius: '3px', display: 'block', marginTop: '8px'}}>
        Proposal Section:
        {'{ProposalSection}'}
        If you have any questions about the proposal...
      </code>

      Image Variables:
      <code style={{backgroundColor: '#f3f4f6', padding: '2px 4px', borderRadius: '3px', display: 'block', marginTop: '8px'}}>
        Photo:
        {'{HeadshotImage}'}
        Nicolas Fry, CEO
      </code>

    ✨ This format ensures variables work correctly and content flows properly

:::tip Key Takeaway
Notice how in the correct examples, each variable is **completely isolated** on its own line with blank lines above and below. This separation is crucial for rich text, images, and section variables to function properly.
:::

### 3. Use Paragraph Markers to Debug

One of the most common mistakes is thinking a variable is on its own line when it's not. To be sure, turn on the paragraph marker tool:

**In Microsoft Word:**
- Click the paragraph icon (¶) to reveal hidden spaces and line breaks
- It's the fastest way to catch formatting issues before they break your template

**In Google Docs:**
- Go to **View → Show non-printing characters**
- You'll get the same results as Word

![Paragraph marker tool location in Word and Google Docs toolbars](https://docs.turbodocx.com/img/how_to_create_a_template/paragraphtool.png)

When you activate the tool, it will resemble the image below. Since `{CustomerName}` is plain text, it can be incorporated into a paragraph. However, we will be utilizing a chart in Rich Text for `{Scope}`, so it needs to be on its own line. Paragraph symbols will indicate this distinction clearly.

![Paragraph markers showing inline text variable vs. section variable on its own line](https://docs.turbodocx.com/img/additional_information/ptoolexample.png)

### 4. Images Must Be PNG or JPEG

Your document or presentation can only carry **PNG** and **JPEG** images. If you put any other
format into a rich text or image variable, TurboDocx leaves a short message in its place:

```
[Image not supported: SVG — use PNG or JPEG (diagram.svg)]
```

That message tells you three things: the format that wasn't accepted, what to use instead, and
the file name, so you can find it among many images.

**Formats that get replaced with the message:** SVG, GIF, WebP, BMP, TIFF, HEIC, AVIF and ICO.

:::caution The editor will show you the image anyway

The rich text editor previews SVGs, GIFs and WebP files perfectly well, because your browser can
display them even though a Word or PowerPoint file can't store them. So an image can look right
while you're editing and still be replaced in the finished deliverable.

If you see the "Image not supported" message in a document you just generated, that's why —
nothing is broken. Convert the image and generate again.

:::

**How to fix it:** open the image in any editor and re-save it as PNG or JPEG, then replace it in
your variable. For logos and diagrams saved as SVG, exporting at 2× the size you need keeps them
looking sharp.

## Quick Troubleshooting Steps

When your variables aren't working, follow these steps in order:

### 1. Check Variable Naming
No spaces inside brackets - use `{CustomerName}` not `{Customer Name}`

### 2. Verify Line Placement  
Variables for images, rich text, or sections must be on their own line

### 3. Use Paragraph Markers
Turn on ¶ symbols to see hidden formatting issues

### 4. Check Your Image Formats
Only PNG and JPEG can go into a deliverable — convert SVG, GIF, WebP, BMP, TIFF, HEIC, AVIF and ICO first

### 5. For Presentation Templates
Use invisible rectangle shapes, not text boxes → [See presentation setup guide](./How-to-Create-a-Presentation-Template)

### 6. Test Your Template
Create a simple deliverable to verify everything works → [Learn how to create deliverables](./How-to-Create-a-Deliverable)

:::tip Advanced Troubleshooting & Best Practices

**If variables still aren't working:**
- **Start simple:** Test with basic text variables first, then add complex ones
- **Double-check spacing:** Use paragraph markers to confirm variables are completely isolated
- **For presentations:** Ensure shapes are truly invisible (no fill, no outline)

**Best practices for success:**
- **Test your template** by creating a deliverable before finalizing → [See how](./How-to-Create-a-Deliverable)
- **Keep variable names descriptive** but concise
- **Use consistent formatting** across all templates → [Document templates](./How-to-Create-a-Document-Template) | [Presentation templates](./How-to-Create-a-Presentation-Template)

:::

## Need More Help?

Still stuck? We're here to help! Check out our comprehensive guides:

- [📄 Document Templates](./How-to-Create-a-Document-Template) - Learn to create Word/Google Doc templates
- [📊 Presentation Templates](./How-to-Create-a-Presentation-Template) - Learn to create PowerPoint templates  
- [🎯 Create Deliverables](./How-to-Create-a-Deliverable) - Learn to generate documents from templates
- [📚 Full Documentation](https://docs.turbodocx.com) - Complete TurboDocx documentation

If you need additional help, don't hesitate to reach out to our support team.
