How do I Configure Logging for Volume License Troubleshooting?

This page explains how to capture detailed diagnostic logs for troubleshooting problems with your iText license file, particularly for Volume (Capacity Rental) licenses. It applies to the current iText Core release line (Java and .NET).

Use this when you see symptoms such as:

• Generated documents show the AGPL producer line instead of your licensed one.

• A LicenseKeyException or version-mismatch error is thrown at startup.

• The warning "The 'itext-licensekey-volume' library is required for your license type, but it is missing or outdated" (see the Volume Counter installation guide).

• The warning "iText was unable to record your usage information as required by the Capacity Rental License" (also covered in the guide above).

Steps to collect logs

1. Add the logging configuration for your platform (below).

2. Reproduce the licensing issue.

3. Collect the generated itext-license-debug.log file.

Java

iText's Java modules log through the SLF4J facade, using the com.itextpdf package as the logger namespace. In the example below, we have used the Log4j binding.

Log4j configuration

Add or update the following file : src/main/resources/log4j.properties

Configuration properties

log4j.rootLogger=TRACE, stdout, file

log4j.appender.stdout=org.apache.log4j.ConsoleAppender
log4j.appender.stdout.Target=System.out
log4j.appender.stdout.layout=org.apache.log4j.PatternLayout
log4j.appender.stdout.layout.ConversionPattern=%d{ISO8601} %-5p [%t] %c - %m%n

log4j.appender.file=org.apache.log4j.FileAppender
log4j.appender.file.File=src/main/resources/itext-license-debug.log
log4j.appender.file.Append=false
log4j.appender.file.layout=org.apache.log4j.PatternLayout
log4j.appender.file.layout.ConversionPattern=%d{ISO8601} %-5p [%t] %c - %m%n

The log file should be created at: src/main/resources/itext-license-debug.log

🔹 For application servers, Docker, Kubernetes or Packaged JAR/WAR deployments, use a writable path instead. For example : log4j.appender.file.File=/tmp/itext-license-debug.log

🔹 For Tomcat this would be : log4j.appender.file.File=${catalina.base}/logs/itext-license-debug.log

.NET

The logging mechanism in .NET differs somewhat from Java, so enabling detailed diagnostics requires a combination of additional code and supporting packages. Since iText relies on ITextLogManager, we also need to configure it appropriately to capture network activity, TLS/SSL diagnostics, and complete exception stack traces.

Required NuGet Packages

Microsoft.Extensions.Logging

Microsoft.Extensions.Logging.Console

Configuration

Before enabling iText logs, initialize the NetLogs listener first so that System.Net/TLS activity is captured from the beginning of the license-loading flow.

For example:

using var netLogs = new NetLogs();

🔹 Enable iText Logs

using Microsoft.Extensions.Logging;
using System.Diagnostics.Tracing;

..

using var loggerFactory = LoggerFactory.Create(builder =>
{
    builder.ClearProviders();
    builder.SetMinimumLevel(LogLevel.Trace);
    builder.AddConsole();
});

ITextLogManager.SetLoggerFactory(loggerFactory);
//Load your iText license 

🔹 Enable Network/TLS Logs

sealed class NetLogs : EventListener
{
    protected override void OnEventSourceCreated(EventSource source)
    {
        if (source.Name.StartsWith("System.Net"))
        {
            EnableEvents(source, EventLevel.Verbose, EventKeywords.All);
        }
    }

    protected override void OnEventWritten(EventWrittenEventArgs e)
    {
        Console.WriteLine($"[{e.EventSource.Name}] {e.EventName}");

        if (e.PayloadNames == null || e.Payload == null)
            return;

        for (int i = 0; i < e.Payload.Count; i++)
        {
            Console.WriteLine($"  {e.PayloadNames[i]} = {e.Payload[i]}");
        }
    }
}

Saving output to a file

dotnet run > itext-license-debug.log 2>&1

🔹 For Kubernetes/Openshift deployments, collect logs from the pod instead:

kubectl logs <pod-name> > itext-license-debug.log 2>&1

🔹 If you hit a System.MissingMethodException referencing Amazon.CognitoIdentity, that's a separate, known AWS SDK version-conflict issue — see Resolving MissingMethodException and AWS SDK Compatibility in .NET Applications rather than continuing down this logging path.