Handle Common Template and Data Errors Leave feedback

Overview

Error handling is crucial when generating documents from templates and data sources. GroupDocs.Assembly for Java reports problems with templates, data sources, or assembly operations through standard Java exceptions. Understanding common error scenarios and how to handle them improves the reliability of your document generation code.

The main exception types are:

IllegalStateException - template syntax errors, missing member errors, expression evaluation errors, data source errors (such as a null data source object), and unsupported output formats; the original exception is available through getCause()
FileNotFoundException - a missing template file or a non-existent output folder
IllegalArgumentException - a null or empty template or output path
NullPointerException - a null template or output stream

Here are the steps to handle errors:

Wrap assembly operations in try-catch blocks
Catch specific exception types
Validate data sources before assembly
Handle missing members gracefully
Log errors for debugging

Note
GroupDocs.Assembly provides detailed error messages that help identify the exact location and cause of template or data errors.

Basic Error Handling

Wrap assembly operations in try-catch blocks:

import com.groupdocs.assembly.*;

public class PersonData
{
    private String name;
    private int age;

    public PersonData(String name, int age)
    {
        this.name = name;
        this.age = age;
    }

    public String getName() { return name; }
    public int getAge() { return age; }
}

public static void basicErrorHandling()
{
    try
    {
        PersonData data = new PersonData("John Doe", 30);

        DocumentAssembler assembler = new DocumentAssembler();
        assembler.assembleDocument("Template.docx", "Output.docx",
            new DataSourceInfo(data, "data"));

        System.out.println("Document assembled successfully.");
    }
    catch (Exception ex)
    {
        System.out.println("Error assembling document: " + ex.getMessage());
        // Handle error appropriately
    }
}

Handle Template Syntax Errors

Catch and handle template syntax errors. In Java, template syntax and expression errors are reported as IllegalStateException:

import com.groupdocs.assembly.*;

public static void handleTemplateErrors()
{
    try
    {
        PersonData data = new PersonData("John Doe", 30);

        DocumentAssembler assembler = new DocumentAssembler();
        assembler.assembleDocument("Template.docx", "Output.docx",
            new DataSourceInfo(data, "data"));
    }
    catch (IllegalStateException ex)
    {
        System.out.println("Template error: " + ex.getMessage());
        System.out.println("Error details: "
            + (ex.getCause() != null ? ex.getCause().getMessage() : null));
        // Log error, notify user, or use fallback template
    }
    catch (Exception ex)
    {
        System.out.println("Unexpected error: " + ex.getMessage());
    }
}

Instead of throwing an exception, the engine can write template syntax error messages directly into the output document. Set the DocumentAssemblyOptions.INLINE_ERROR_MESSAGES option and check the value returned by assembleDocument: it is false when assembly was interrupted by a template syntax error.

import com.groupdocs.assembly.*;

public static void handleTemplateErrorsInline() throws Exception
{
    PersonData data = new PersonData("John Doe", 30);

    DocumentAssembler assembler = new DocumentAssembler();
    assembler.setOptions(DocumentAssemblyOptions.INLINE_ERROR_MESSAGES);

    boolean success = assembler.assembleDocument("Template.docx", "Output.docx",
        new DataSourceInfo(data, "data"));

    if (!success)
    {
        // Output.docx contains the error message next to the faulty tag, for example:
        // <<[data.getName(] Error! An expression is expected. >>
        System.out.println("Template contains syntax errors. See Output.docx for details.");
    }
}

For more details, see Use of In-line Syntax Error Messages into Templates.

Handle Missing Data Members

Handle cases where template references missing data members:

import com.groupdocs.assembly.*;

public class NameOnlyData
{
    private String name;

    public NameOnlyData(String name)
    {
        this.name = name;
    }

    public String getName() { return name; }
}

public static void handleMissingMembers()
{
    try
    {
        // Data doesn't have all members referenced in template
        NameOnlyData data = new NameOnlyData("John Doe");
        // Template might reference data.getEmail() which doesn't exist

        DocumentAssembler assembler = new DocumentAssembler();

        // Option 1: Allow missing members (returns null/empty)
        assembler.setOptions(assembler.getOptions() | DocumentAssemblyOptions.ALLOW_MISSING_MEMBERS);

        assembler.assembleDocument("Template.docx", "Output.docx",
            new DataSourceInfo(data, "data"));
    }
    catch (Exception ex)
    {
        System.out.println("Error: " + ex.getMessage());
    }
}

Validate Data Before Assembly

Validate data sources before assembly. Passing a null data source object causes assembleDocument to throw an IllegalStateException:

import com.groupdocs.assembly.*;
import java.util.*;

public class Product
{
    private String name;
    private double price;

    public Product(String name, double price)
    {
        this.name = name;
        this.price = price;
    }

    public String getName() { return name; }
    public double getPrice() { return price; }
}

public static void validateDataBeforeAssembly()
{
    List<Product> products = new ArrayList<>();
    // products might be empty or null

    if (products == null || products.isEmpty())
    {
        System.out.println("Warning: No products to process.");
        return;
    }

    try
    {
        DocumentAssembler assembler = new DocumentAssembler();
        // Pass an array (or a POJO with a typed getter) so that the engine knows the element type
        assembler.assembleDocument("Template.docx", "Output.docx",
            new DataSourceInfo(products.toArray(new Product[0]), "products"));

        System.out.println("Document assembled successfully.");
    }
    catch (Exception ex)
    {
        System.out.println("Error: " + ex.getMessage());
    }
}

Handle File Not Found Errors

Check if template file exists:

import com.groupdocs.assembly.*;
import java.io.*;
import java.nio.file.*;

public static void handleFileNotFound()
{
    String templatePath = "Template.docx";

    if (!Files.exists(Paths.get(templatePath)))
    {
        System.out.println("Template file not found: " + templatePath);
        return;
    }

    try
    {
        PersonData data = new PersonData("John Doe", 30);

        DocumentAssembler assembler = new DocumentAssembler();
        assembler.assembleDocument(templatePath, "Output.docx",
            new DataSourceInfo(data, "data"));

        System.out.println("Document assembled successfully.");
    }
    catch (FileNotFoundException ex)
    {
        System.out.println("File not found: " + ex.getMessage());
    }
    catch (Exception ex)
    {
        System.out.println("Error: " + ex.getMessage());
    }
}

Handle Data Type Errors

Validate data types before assembly:

import com.groupdocs.assembly.*;

public class Invoice
{
    private String customerName;
    private Double amount; // Nullable

    public String getCustomerName() { return customerName; }
    public void setCustomerName(String value) { this.customerName = value; }
    public Double getAmount() { return amount; }
    public void setAmount(Double value) { this.amount = value; }
}

public static void handleDataTypeErrors()
{
    Invoice invoice = new Invoice();
    invoice.setCustomerName("John Doe");
    invoice.setAmount(null); // Outputs an empty value; calling a method on it in the template fails

    try
    {
        DocumentAssembler assembler = new DocumentAssembler();
        assembler.assembleDocument("Template.docx", "Output.docx",
            new DataSourceInfo(invoice, "invoice"));
    }
    catch (Exception ex)
    {
        System.out.println("Data type error: " + ex.getMessage());
        // Handle null values or provide defaults
    }
}

Comprehensive Error Handling

Combine multiple error handling strategies:

import com.groupdocs.assembly.*;
import java.io.*;
import java.nio.file.*;

public static void comprehensiveErrorHandling()
{
    String templatePath = "Template.docx";
    String outputPath = "Output.docx";

    // Validate inputs
    if (templatePath == null || templatePath.isEmpty() || !Files.exists(Paths.get(templatePath)))
    {
        System.out.println("Invalid template path.");
        return;
    }

    try
    {
        PersonData data = new PersonData("John Doe", 30);

        // Validate data
        if (data == null)
        {
            System.out.println("Data source is null.");
            return;
        }

        DocumentAssembler assembler = new DocumentAssembler();

        // Configure error handling options
        assembler.setOptions(assembler.getOptions() | DocumentAssemblyOptions.ALLOW_MISSING_MEMBERS);

        assembler.assembleDocument(templatePath, outputPath,
            new DataSourceInfo(data, "data"));

        System.out.println("Document assembled successfully.");
    }
    catch (IllegalStateException ex)
    {
        System.out.println("Assembly error: " + ex.getMessage());
        if (ex.getCause() != null)
        {
            System.out.println("Inner exception: " + ex.getCause().getMessage());
        }
        // Log detailed error information
    }
    catch (FileNotFoundException ex)
    {
        System.out.println("File not found: " + ex.getMessage());
    }
    catch (IOException ex)
    {
        System.out.println("I/O error (for example, access denied): " + ex.getMessage());
    }
    catch (Exception ex)
    {
        System.out.println("Unexpected error: " + ex.getMessage());
        ex.printStackTrace();
    }
}

Handle Stream Errors

Properly handle stream-related errors:

import com.groupdocs.assembly.*;
import java.io.*;

public static void handleStreamErrors()
{
    try (InputStream templateStream = new FileInputStream("Template.docx");
         OutputStream outputStream = new FileOutputStream("Output.docx"))
    {
        PersonData data = new PersonData("John Doe", 30);

        DocumentAssembler assembler = new DocumentAssembler();
        assembler.assembleDocument(templateStream, outputStream,
            new DataSourceInfo(data, "data"));
    }
    catch (IOException ex)
    {
        System.out.println("IO error: " + ex.getMessage());
    }
    catch (Exception ex)
    {
        System.out.println("Error: " + ex.getMessage());
    }
}

Error Handling Best Practices

Always use try-catch blocks around assembly operations
Validate inputs before assembly (file existence, data null checks)
Use specific exception types when possible
Enable ALLOW_MISSING_MEMBERS option if your data structure is dynamic
Log errors with sufficient detail for debugging
Provide user-friendly error messages in production code

Warning
Some errors might occur during template evaluation. Always test templates with sample data before deploying to production. Consider using template validation tools or test assemblies.

Advanced Usage Topics

To learn more about detailed error logging, template validation, custom error handling, and debugging techniques, please refer to the advanced usage section.

More resources

GitHub Examples

You may easily run the code above and see the feature in action in our GitHub examples:

Free Online Apps

Along with the full-featured Java library, we provide simple but powerful free online apps.

To assemble documents from templates and data sources, you can use the online apps from the GroupDocs.Assembly App Product Family.

We value your opinion. Your feedback will help us improve our documentation.