Troubleshooting

Common issues and solutions when working with PPTXMailMerge.

Placeholders Not Being Replaced

Issue: Placeholders remain as {{variable_name}} in the output

Possible Causes:

  1. Case Mismatch: Placeholder names are case-sensitive

    • ✅ Solution: Ensure {{name}} in template matches name in data (not Name or NAME)

  2. Spacing Issues: Extra spaces in placeholder syntax

    • ✅ Solution: Use {{variable_name}} not {{ variable_name }} or {{variable_name }}

  3. Field Name Mismatch: Field name in data doesn't match placeholder

    • ✅ Solution: Check your data file and ensure field names exactly match placeholder names

  4. Data File Not Loaded: Data file wasn't properly uploaded or processed

    • ✅ Solution: Re-upload your data file and verify it's the correct format

Empty Slides or Missing Data

Issue: Slides are created but contain no data or empty placeholders

Possible Causes:

  1. Empty Rows: Your data file contains empty rows

    • ✅ Solution: Remove empty rows from your data file

  2. Missing Fields: Data doesn't contain the expected fields

    • ✅ Solution: Verify your data structure matches your template placeholders

  3. Null Values: Data contains null or empty values

    • ✅ Solution: This is expected behavior - null values result in empty placeholders

File Upload Issues

Issue: Cannot upload file or file is rejected

Possible Causes:

  1. File Size: File exceeds maximum size limit

    • ✅ Solution: Reduce file size or split into smaller files

  2. File Format: Unsupported file format

    • ✅ Solution: Ensure you're using:
      • .pptx for PowerPoint templates
      • .json, .xlsx, or .csv for data files

  3. File Corruption: File is corrupted or incomplete

    • ✅ Solution: Re-save or re-export your file

Data Format Issues

JSON Files

Common Issues:

  • Invalid JSON syntax
    • ✅ Solution: Use a JSON validator to check your file
  • Missing commas or brackets
    • ✅ Solution: Verify JSON structure is valid
  • Encoding issues
    • ✅ Solution: Save file as UTF-8

Excel Files

Common Issues:

  • Wrong file format (.xls instead of .xlsx)
    • ✅ Solution: Save as .xlsx format
  • Merged cells in header row
    • ✅ Solution: Unmerge cells in header row
  • Multiple header rows
    • ✅ Solution: Ensure only first row contains headers

CSV Files

Common Issues:

  • Unquoted fields with commas
    • ✅ Solution: Quote fields containing commas: "field, with, commas"
  • Encoding issues (special characters)
    • ✅ Solution: Save as UTF-8 encoding
  • Inconsistent delimiters
    • ✅ Solution: Use consistent delimiter (comma recommended)

Template Issues

Issue: Template doesn't work as expected

Possible Causes:

  1. Complex Formatting: Very complex PowerPoint formatting may not be preserved

    • ✅ Solution: Simplify formatting or test with a basic template first

  2. Protected Slides: Slides are protected or locked

    • ✅ Solution: Remove protection from your template

  3. Unsupported Elements: Template contains unsupported PowerPoint features

    • ✅ Solution: Avoid complex animations, macros, or embedded objects

Performance Issues

Issue: Merge process is slow or times out

Possible Causes:

  1. Large Data Files: Very large datasets take longer to process

    • ✅ Solution: Split into smaller batches or optimize your data file

  2. Complex Templates: Templates with many elements take longer

    • ✅ Solution: Simplify template where possible

  3. Server Load: High server load may slow processing

    • ✅ Solution: Try again later or contact support

Getting Help

If you're still experiencing issues:

  1. Check Documentation: Review the relevant documentation section
  2. Verify Your Setup: Double-check your template and data files
  3. Test with Sample Data: Try with a simple, known-good example
  4. Contact Support: Reach out through our contact page

Common Error Messages

"Invalid data format"

  • Check that your data file matches the expected format (JSON array, Excel with headers, CSV with headers)

"Template not found"

  • Verify your PowerPoint file was uploaded successfully
  • Check file format is .pptx

"Processing timeout"

  • Your file may be too large or complex
  • Try splitting into smaller files

"Invalid placeholder syntax"

  • Check placeholder syntax: {{variable_name}} (no spaces around variable name)
  • Ensure placeholders are in text elements (not in images or other non-text elements)