Skip to main content
Version: 10.0

Files troubleshooting

Use this guide when you need to collect additional diagnostic information for startup issues, memory problems, unexpected server behavior, or connectivity problems related to the webPDF configuration files.

If you first need to locate the relevant conf/, logs/, temp/, or installation directories, start with Directory structure.

Before you change anything​

  • Prefer the Admin Portal whenever the setting is available there.
  • Record the original values before changing configuration files.
  • Change only one area at a time so that the effect is easy to verify.
  • Revert temporary diagnostic changes after the analysis is complete.
caution

Manual changes to the configuration files can make the server unavailable. Only change configuration files directly when the Admin Portal is not sufficient for the analysis.

1. Identify which runtime mode is active​

Use the correct configuration location for the current operating mode before changing JVM settings.

Windows​

  • webPDF.vmoptions applies when webPDF is started as a console application.
  • webPDF.service.vmoptions applies when webPDF runs as a Windows service.

The default starter files use:

-Xmx4g
-Xms1g

Linux​

  • SysVinit installations usually use webpdf.sh.
  • Systemd installations start webpdf.starter.sh through webpdf.service.
  • Under Systemd, JVM options are typically provided through the JAVA_PARAMETERS environment variable.

If you change the wrong startup path, the expected JVM options will not take effect.

See Java environment for the platform-specific configuration details.

2. Collect support information first​

Before increasing log verbosity or changing multiple settings, download a support package from the Admin Portal.

Recommended workflow:

  1. Open Support information in the Admin Portal.
  2. Select all relevant options.
  3. Choose the timeframe in which the problem occurred.
  4. Download the package before and after reproducing the issue if you need a comparison.

This package is the preferred baseline when Support needs logs and configuration files together.

3. Increase log detail only when needed​

For most cases, first use the temporary Debug mode in the Admin Portal. This avoids a permanent change in conf/log4j2.xml.

Recommended sequence:

  1. Enable debug mode in the Admin Portal.
  2. Reproduce the issue once.
  3. Download the updated Support information.
  4. Set the log level back to info.
danger

Debug logging can slow down the server and generate large log files quickly. Keep it enabled only for the shortest possible time.

When a manual logging change is justified​

If the Admin Portal is not accessible, you can temporarily change the root logger in conf/log4j2.xml:

<Root level="debug">

After the analysis, restore the default level:

<Root level="info">

The default logging configuration writes server log files to the logs/ directory and reloads changes to conf/log4j2.xml automatically.

See Logging for the logging file and behavior.

Review the JVM settings when you see symptoms such as:

  • startup failures after load increases
  • OutOfMemoryError entries in the server log
  • repeated garbage collection pressure
  • slow processing during large or parallel conversions

Start with the active JVM configuration file or startup script and verify:

  • maximum heap size (-Xmx)
  • minimum heap size (-Xms)
  • additional JVM system properties (-D...) used for diagnostics or runtime tuning
tip

Use the Admin Portal to compare the effective memory settings with the values shown in the server's system information.

If you temporarily add diagnostic JVM parameters, remove them again after the analysis unless they are part of the intended production setup.

See Java environment for the configuration locations.

5. Check connector and server configuration​

Review conf/server.xml when the server starts but clients cannot connect as expected.

Typical checks:

  • correct HTTP or HTTPS port
  • connector enabled or disabled as intended
  • correct bind address for the deployment environment
  • TLS keystore and protocol settings if HTTPS is enabled

The default starter configuration uses:

  • HTTP connector enabled on port 8080
  • HTTPS connector disabled on port 8443

If the issue is specifically TLS-related, continue with TLS troubleshooting.

See Server configuration for the relevant file overview.

6. Verify the result after each change​

After changing configuration files:

  1. Restart webPDF if the affected setting is not reloaded automatically.
  2. Verify that the server starts cleanly.
  3. Reproduce the original problem once.
  4. Check whether the logs now contain the expected diagnostic detail.

For conf/log4j2.xml, the logging configuration is reloaded automatically after saving the file. Most other configuration file changes require a restart.

7. Restore the normal state​

After troubleshooting:

  • set the log level back to info
  • remove temporary JVM diagnostic parameters that are no longer needed
  • keep only configuration changes that were intentionally validated
  • create a final support package if you need to document the resolved state