When creating and uploading document templates, you might encounter various errors that prevent templates from working correctly. These issues can cause templates to not autofill properly, display error messages, or fail during document generation. This article provides steps to resolve common placeholder and template problems.

Before you start

To troubleshoot document templates, you need to have access to the Documents section in Personio and the ability to create or edit document templates.

When editing a document template, you must edit the original file and re-upload it to Personio.

Making changes to templates affects all future documents generated from those templates. Existing documents remain unchanged.

Check your placeholder formatting

Issue: 
Your placeholders aren't working correctly, or you're receiving error messages about variable delimiters when trying to use your template.

Possible solution:
Incorrect special characters are the most common cause of placeholder errors. Each placeholder type requires specific bracket formatting to function properly.

1. Review each placeholder in your template.
2. Ensure preset attribute placeholders use double curly brackets: {{placeholder_name}}.
3. Verify that custom attribute placeholders also use double curly brackets: {{Custom Placeholder Name}}.
4. Check that text block placeholders use double square brackets: [[placeholder content]].
5. Confirm gender variable placeholders use double pipe symbols: ||Male|Female|Diverse|Undefined||.
6. Make sure each opening bracket has a corresponding closing bracket.

Check your file format

Issue:
You receive an error message when trying to upload your template, or the upload process fails without a clear reason.

Possible solution:
Template upload errors often occur when the file format is not supported by Personio's document system.

1. Check that your template file is saved in a supported format.
2. Ensure your file uses one of these extensions: .DOCX, .DOTX, .ODT, or .OTT.
3. If your file is in a different format, open it in your word processor.
4. Save the file again using one of the supported formats.
5. Try uploading the newly saved file to Personio.

Optimize embedded images

Issue:
Your template file doesn't display correctly in a PDF viewer.

Possible solution:
Embedded images can create issues when displaying documents in a PDF viewer.

1. Compress or delete the cropped parts of an image:
   • Delete cropped areas of a picture (scroll to the bottom of the article)
   • Delete all picture editing data (scroll to the bottom of the article)
2. Replace any image in a .pdf format with a .png file.
3. If you can't replace the files, ensure the .pdf files are flattened before uploading them again. If you're not sure how to do this with the software you used to create the file, print the .pdf with a PDF printer.

Remove problematic document elements

Issue:
Your template file is in the correct format, but the upload still fails or produces error messages.

Possible solution:
Certain document elements can interfere with the template upload process and cause errors.

1. Open your template file in your word processor.
2. Check for and remove headers from your document.
3. Remove any footers that might be present.
4. Delete any images embedded in the template. If you need to keep the images, optimize them.
5. Remove or simplify complex tables in the document.
6. Save the modified template file.
7. Try uploading the template again after removing each element.
8. If the upload succeeds after removing a specific element, that element was causing the issue.

Verify placeholder formatting

Issue:
Your template uploads but doesn't work correctly, or you receive placeholder-related error messages.

Possible solution:
Placeholder formatting issues can cause upload problems or prevent templates from functioning properly after upload.

1. Review all placeholders in your template for correct formatting.
2. Check that attribute placeholders use double curly brackets: {{placeholder_name}}.
3. Verify that text block placeholders use double square brackets: [[content]].
4. Ensure gender variables follow the correct format: ||Male|Female|Diverse|Undefined||.
5. Confirm that each opening bracket has a corresponding closing bracket.
6. Remove any placeholders that begin with numbers or contain only numbers.
7. Save your template after making corrections and try uploading again.

Verify placeholder spelling and capitalization

Issue:
Your custom attribute placeholders appear as free-text fields instead of autofilling, or placeholders show up empty in document previews.

Possible solution:
Placeholder names must match exactly with the corresponding attributes in Personio, including spelling and capitalization.

1. Go to your employee profile attributes in Personio.
2. Compare the exact attribute names with your placeholder text.
3. For preset placeholders, ensure you use lowercase letters and underscores (e.g., {{first_name}}, not {{First_Name}}).
4. For custom attributes, match the exact capitalization from Personio (e.g., {{Name Bank}}, {{IBAN}}).
5. Check that custom placeholder names are written in the same language as your Personio account.
6. Verify that signature placeholders use consistent spelling and capitalization throughout the document (@@signer@@ vs @@Signer@@).
7. Ensure placeholders don't begin with numbers or contain only numbers.

Remove incompatible characters

Issue: 
Your template preview shows errors or the template fails to work properly after uploading.

Possible solution:
Certain special characters in multi-line text fields can cause template malfunctions.

1. Review your template for problematic characters like "", ;, `, ', ä, ö, ü, …, or •.
2. Check employee profiles that will use this template for these characters in multi-line fields.
3. If you find incompatible characters, download your template file.
4. Remove or replace the problematic characters in the template.
5. Upload the corrected template to Personio again.
6. Test the template with a document preview to ensure it works correctly.

Ensure proper placeholder structure for complex formats

Issue:
Your gender variables, text blocks, or optional placeholders aren't displaying correctly in generated documents.

Possible solution:
Complex placeholder formats require specific syntax to function properly.

1. For gender variables, verify the format: ||Male option|Female option|Diverse option|Undefined option||.
2. Check that text block placeholders follow this structure: [[Block name[Option 1: text][Option 2: text]]].
3. For optional placeholders, ensure proper nesting with square and curly brackets.
4. Test each complex placeholder type individually to isolate formatting issues.
5. Refer to placeholder examples and copy the exact syntax structure.

Verify employee profile data completeness

Issue:
Attribute placeholders appear empty in generated documents even though the formatting is correct.

Possible solution:
Placeholders can only autofill with data that exists in the employee's Personio profile.

1. Go to the employee profile you're testing with.
2. Check that all relevant attribute fields contain data.
3. Verify that custom attributes have been filled in for the employee.
4. Ensure date fields contain valid dates in the correct format.
5. Test your template with an employee profile that has complete information.

Check number formatting in document templates

Issue:
A number attribute placeholder outputs the value without thousand separators (for example, 864000 instead of 864.000).

Possible solution:
This is a known limitation of document templates. Number attributes display thousand separators in employee profiles but not in generated documents.

As a workaround, you could store the value as a single-line text attribute with the separator included (for example, "864.000"). Keep in mind that Personio cannot use text attributes for calculations. We don't recommend this for values you need to calculate with.