Reference Guide

Logging & Debug Configuration

GeoServer uses a robust, hierarchical logging system built on Apache Log4j 2. This guide covers configuring log outputs, enabling debug modes for specific subsystems, and troubleshooting common operational issues.

ℹ️ Quick Note

Changes to logging configuration take effect immediately in most cases. No server restart is required unless modifying core Java system properties.

Overview

The logging system routes events through appenders (Console, File, Rolling File, Syslog, HTTP) and filters them based on levels. GeoServer ships with a default configuration optimized for production, but developers and administrators can override it via environment variables, system properties, or the web admin interface.

Log Levels

Log levels determine the verbosity of output. Higher levels include all messages from lower levels plus their own.

Level	Description	Use Case
`OFF`	Disables all logging	Not recommended
`FATAL`	Severe errors that cause abrupt termination	Production emergencies
`ERROR`	Error events that may allow app to continue	Default production level
`WARN`	Warning events about unusual conditions	Staging / monitoring
`INFO`	Informational messages about runtime progress	Standard operations
`DEBUG`	Fine-grained diagnostic information	Troubleshooting & development
`TRACE`	Extremely verbose, method-by-method execution	Deep debugging only

Configuration

Environment Variables

Override logging behavior without editing config files:

Bash / Zsh

export GEOSERVER_LOG_LEVEL=DEBUG
export GEOSERVER_LOG_DIR=/var/log/geoserver
export GEOSERVER_LOG_FILE=geoserver-debug.log

System Properties

Pass JVM flags directly when starting the web app:

Java Startup

java -Dorg.geotools.referencing.forceXY=true \
     -DGEOSERVER_LOG_LEVEL=DEBUG \
     -jar start.jar

Web Admin Interface

Navigate to Settings → Logging in the GeoServer web UI. You can dynamically adjust levels per package (e.g., org.geotools, org.geoserver.wfs) and view live console output.

Debug Mode

Debug mode enables request tracing, parameter inspection, and stack dump generation. It is not recommended for production due to performance overhead and information leakage risks.

Enabling Debug

Go to Security → Debug in the web admin.
Set DEBUG=true in the global properties or via the UI toggle.
Request logs will now include full query parameters, authentication headers, and processing timelines.

⚠️ Security Warning

Debug mode exposes request payloads, file paths, and stack traces. Always restrict access to internal networks or disable in production environments.

Common Debug Flags

Flag	Target
`-Dorg.geotools.shapefile.ignoreCase=true`	Shapefile driver case sensitivity
`-DGEOSERVER_CSRF_DISABLED=true`	Bypass CSRF validation (testing only)
`-DGEOSERVER_LOG_REQUESTS=true`	Log HTTP request/response metadata
`-DGEOSERVER_LOG_SQL=true`	Dump JDBC queries to console

Troubleshooting

Out of Memory / Heap Dump

If GeoServer crashes with OutOfMemoryError, capture a heap dump for analysis:

JVM Options

-XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/var/log/geoserver/heapdump.hprof

Thread Deadlocks

Use jstack <pid> or enable -Djava.lang.management=true to generate thread dumps. Look for threads blocked on org.geoserver.wms or org.geotools.data locks.

Missing Log Files

Verify the GEOSERVER_DATA_DIR/logs directory exists and is writable by the JVM user. Rotate logs using the built-in RollingFileAppender configuration to prevent disk exhaustion.

Appendix: Sample Log4j2 Snippet

log4j2.xml (Custom Appender)

<RollingFile name="GeoServerDebug" fileName="${sys:GEOSERVER_LOG_DIR}/geoserver-debug.log"
             filePattern="${sys:GEOSERVER_LOG_DIR}/geoserver-debug-%d{yyyy-MM-dd}.log.gz"
             immediateFlush="true">
    <PatternLayout pattern="[%d{HH:mm:ss,SSS}] [%t] %p %c - %m%n"/>
    <Policies>
        <TimeBasedTriggeringPolicy modulate="true" interval="1"/>
        <SizeBasedTriggeringPolicy size="100MB"/>
    </Policies>
    <DefaultRolloverStrategy max="30"/>
</RollingFile>

← Security & Authentication Backup & Restore →