Support Center

Error Codes & Troubleshooting

Reference guide for common GeoServer error codes, their root causes, and verified resolutions.

🔍
GS-401 Medium
Authentication Failed
Invalid credentials or expired token provided during service request.
CauseWrong API key, expired session, or misconfigured security realm.
FixVerify credentials in admin panel, rotate tokens, or check `security.xml` permissions.
CRS-101 Critical
Invalid Coordinate Reference System
Specified CRS is malformed, unsupported, or lacks transformation parameters.
CauseMissing EPSG definition, custom WKT syntax error, or datum shift missing.
FixValidate WKT in GeoServer CRS editor, ensure PROJ datums are installed, or switch to standard EPSG codes.
WMS-201 Medium
Layer Rendering Timeout
Map request exceeded the configured render timeout threshold.
CauseLarge bounding box, high resolution request, or unoptimized SLD styling.
FixEnable WMS caching, increase `REQUEST_TIMEOUT` in `web.xml`, or simplify vector geometries.
DATA-402 Low
Corrupt Metadata or Schema
Published datastore contains broken indexes, missing files, or schema mismatches.
CauseIncomplete upload, database migration error, or missing `.prj`/`.shx` files.
FixRe-publish layer, validate with GDAL, or repair indexes via Datastore Maintenance.
CONN-501 Critical
Database Connection Pool Exhausted
GeoServer cannot acquire a new DB connection due to pool limits or dead locks.
CauseLong-running queries, uncommitted transactions, or low `maxActive` pool setting.
FixIncrease pool size in `datastore.xml`, optimize slow queries, or enable connection idle timeout.
API-601 Low
Invalid OGC Request Structure
Malformed XML/JSON request or missing mandatory OGC parameters.
CauseTypo in `SERVICE`/`VERSION`, invalid envelope format, or unsupported output format.
FixValidate request against OGC specs, use built-in request builder, or check MIME type compatibility.
SERVER-703 Critical
Java Heap Space Exhaustion
Application crashed due to insufficient JVM memory allocation.
CauseLarge raster processing, memory leak in plugins, or default Tomcat JVM limits.
FixSet `-Xmx4g` in `setenv.sh`, monitor heap with JVisualVM, or enable native memory tracking.
CACHE-801 Medium
Tile Cache Write Failure
Geotools cache cannot write tile directories to the configured disk path.
CauseCauseInsufficient disk space, wrong folder permissions, or disk quota reached.
FixGrant `geoserver:geoserver` write access to cache dir, clean expired tiles, or move to larger volume.