Table of Contents

Debugging and troubleshooting

This page provides practical guidance for diagnosing and resolving issues when working with List & Label Cross Platform.

Understanding LLCP errors

LLCP errors typically fall into these categories:

Configuration errors
Incorrect project file paths, missing licensing information, or invalid export settings.

Data binding errors
Connection failures, schema mismatches, or data provider configuration issues.

Runtime errors
Exceptions during report generation, often related to expression evaluation, layout constraints, or resource access.

Rendering errors
Missing fonts, unsupported features in converted projects, or layout issues.

Platform errors
Missing native dependencies (Linux libraries) or file system permission issues.

Tip

Most errors provide detailed messages that identify the issue. Read exception messages carefully before troubleshooting.

Error handling

List & Label Cross Platform throws a ListLabelException whenever an error occurs during report generation. The exception includes a detailed message to help pinpoint the issue.

Example:

try
{
    listLabel.Export(exportConfiguration);
}
catch (ListLabelException ex)
{
    Console.WriteLine("An error occurred: " + ex.Message);
    // Additional error handling or logging
}

Logging

Logging is critical for troubleshooting. The ListLabel class supports logging via its Logger property, allowing you to use built-in solutions or integrate with popular frameworks.

Tip

Once the debugging tool Debwin4 is started in Cross Platform logging mode, every ListLabel instance is automatically configured with a dedicated logger. This logger uses the UDP protocol to transmit all logging output directly to Debwin4, ensuring that diagnostic and debug information is captured in real time without requiring any additional setup.

Using DebwinLogger

A basic file logging setup independent of Debwin4 and using DebwinLogger can be implemented as follows:

using DebwinLogger logger = new DebwinLogger("path/to/logfile.log", LogLevel.Info);
listLabel.Logger = logger;

Using Serilog for logging

Below is an example of how to configure Serilog as an ILogger implementation and bind it to the ListLabel component:

using Serilog;
using Microsoft.Extensions.Logging;

// Configure Serilog
Log.Logger = new LoggerConfiguration()
    .MinimumLevel.Debug()
    .WriteTo.Console()
    .WriteTo.File("logs/listLabel.log", rollingInterval: RollingInterval.Day)
    .CreateLogger();

// Create a logger instance (using Microsoft.Extensions.Logging)
ILogger logger = LoggerFactory.Create(builder =>
{
    builder.AddSerilog();
}).CreateLogger<Program>();

// Assign the logger to ListLabel
listLabel.Logger = logger;
Tip
  • Set up logging early in your application to capture initialization issues.
  • Ensure that the log file path is accessible and has proper write permissions.
  • Use appropriate log levels (Debug, Info, Error) to filter messages based on your needs.

Common issues and resolutions

Missing dependencies (Linux)

Symptom: Application crashes on startup or during rendering with messages about missing native libraries.

Cause: Required system libraries for font handling and image rendering are not installed.

Solution: Install required packages:

Debian/Ubuntu:

apt-get install -y libc6 libfontconfig1 libfreetype6 libpng16-16 libjpeg62-turbo libgif7 fonts-dejavu-core

Alpine:

apk add --no-cache libc6-compat fontconfig freetype libpng libjpeg-turbo giflib ttf-dejavu

Also ensure you reference the SkiaSharp.NativeAssets.Linux NuGet package in your project.

Incorrect file paths

Symptom: ListLabelException indicating the project file cannot be found or opened.

Cause: The AutoProjectFile property points to an incorrect or non-existent file.

Solution:

  • Verify the file path is correct and accessible
  • Use absolute paths or ensure relative paths are resolved from the correct working directory
  • Check file system permissions in containerized or cloud environments
  • For cloud scenarios, consider using an IRepository implementation instead of file paths

Licensing problems

Symptom: Reports contain a trial watermark or licensing errors occur.

Cause: The LicensingInfo property is incorrect, missing, or the edition type does not match your license.

Solution:

  • Verify your LicensingInfo string matches the license you received
  • Ensure you are using the correct edition (Enterprise vs. Professional)
  • Contact combit support if licensing issues persist

Font rendering issues

Symptom: Text appears incorrectly, fonts are substituted, or characters are missing.

Cause: Required fonts are not installed on the system, or font cache is outdated.

Solution:

  • Install the fonts used by your reports on the target system
  • On Linux, run fc-cache -f to rebuild the font cache
  • Consider embedding fonts in your container image (see Deployment guides)
  • Use widely available fonts (like DejaVu) to improve cross-platform compatibility

Data binding failures

Symptom: Empty reports, missing fields, or ListLabelException during export.

Cause: Data source is null, empty, or incorrectly configured.

Solution:

  • Verify the data source contains data before calling Export
  • Check that the data provider is correctly initialized
  • Ensure field names in the report match the data source schema
  • Enable logging to see data provider activity
  • See Providing data for troubleshooting data provider issues

Expression evaluation errors

Symptom: ListLabelException mentioning invalid expressions or syntax errors.

Cause: Expressions in the report contain syntax errors or reference fields that don't exist.

Solution:

  • Review the exception message for the problematic expression
  • Verify field names and expression syntax in the project file
  • Test expressions in isolation before embedding them in reports
  • Use the LL.IsCrossPlatform identifier to conditionally handle differences between Classic and Cross Platform

Performance issues

Symptom: Report generation is slower than expected or consumes excessive memory.

Cause: Large datasets, complex layouts, inefficient data providers, or resource constraints.

Solution:

  • Profile report generation to identify bottlenecks (use logging with LogLevel.Debug)
  • Optimize data provider queries (add indexes, filter data)
  • Limit data volume in reports (pagination, filtering)
  • Ensure sufficient memory and CPU resources
  • Consider horizontal scaling for high-volume scenarios
  • See Deployment guides for scalability considerations

Platform-specific errors

Symptom: Reports work on Windows but fail on Linux or macOS.

Cause: Missing dependencies, path separator issues, or case-sensitive file systems.

Solution:

  • Use Path.Combine and Path.DirectorySeparatorChar for file paths
  • Ensure file names match case exactly on case-sensitive file systems
  • Install required native libraries (see "Missing dependencies" above)
  • Test on target platforms early in development

Systematic troubleshooting workflow

When encountering an issue:

  1. Read the exception message carefully
    Most errors include specific details about the problem.

  2. Enable detailed logging
    Set LogLevel.Debug or LogLevel.Trace to capture diagnostic information.

  3. Isolate the problem

    • Does it occur with all reports or just one?
    • Does it happen with different data sources?
    • Can you reproduce it in a minimal test case?

  4. Check the basics

    • File paths and permissions
    • Licensing configuration
    • Data source availability
    • Required dependencies installed

  5. Review recent changes

    • What changed since it last worked?
    • New reports, data sources, or deployment environment?

  6. Test in isolation

    • Create a minimal console application to reproduce the issue
    • Remove unrelated code and dependencies

  7. Consult documentation

  8. Seek support

Production monitoring recommendations

For production deployments:

Implement health checks

  • Verify LLCP can generate a simple test report on startup
  • Include health check endpoints in web applications
  • Monitor health check failures and alert appropriately

Track key metrics

  • Report generation success/failure rate
  • Average report generation time
  • Memory usage trends
  • Queue depths (if using background processing)

Structured logging

  • Use log aggregation (ELK, Application Insights, CloudWatch)
  • Include correlation IDs to trace requests across services
  • Log report generation start/end with timing information
  • Capture data about failed reports (report name, user, error type)

Error budgets

  • Define acceptable error rates (e.g., 99.9% success rate)
  • Alert when error rates exceed thresholds
  • Track error trends over time
Important

Production monitoring is essential for scalable, reliable reporting systems. Implement observability from the start, not as an afterthought.

By following these guidelines and using the provided examples, you should be able to troubleshoot and resolve most issues encountered when working with List & Label Cross Platform. If you continue to experience problems, reach out to the Support Team or the community for further assistance.