Sign-in fails
Use a complete, unexpired bootstrap JWT or administrator API key. The catalog encryption key, API-key ID, and API-key prefix are not sign-in credentials. Console access requires super_admin or workspace admin. For OIDC, confirm the exact callback URI and role mappings.
To replace an expired bootstrap token, follow the recovery procedure. Stop the server before opening its catalog with the token command.
The catalog is locked
The catalog supports one active writer. Stop the other neoserver process or container before running administrative commands against the same database. Do not delete the catalog to clear the lock, and do not reinitialize a working deployment.
A store cannot connect
Test the connection in Stores. Check the hostname from the server’s network context, port, database name, credentials, TLS mode, and database health. In the tutorial, PostGIS is db:5432 on the Compose network, not localhost inside the server container.
For file stores, verify that the path exists inside the container, is mounted, and matches the allowed-path policy. For HTTP or S3 data, review remote access settings and the source-specific error.
A published layer returns 403 or 404
Check each boundary independently: store enabled, layer enabled, protocol enabled, workspace role, layer allowed roles, and the actual client credential. Use Endpoints → Check access with my session for a console-session check, then test the client key separately.
An administrator’s success does not imply anonymous or viewer access. Confirm that the requested public identifier and workspace are correct.
A map is blank
Choose Fit for the selected publication. Inspect the dataset’s extent and CRS. Try GeoJSON sampling to check the features, then WMS to check server-side styling. Verify that an appropriate symbolizer exists for the geometry type and that the map request is inside the data’s extent.
A background-free preview is expected when no basemap URL is configured. Missing datum-shift grids can affect precise reprojection; see deployment.
Imports fail
Open the import’s events and error details. Check file type, size limits, allowed paths, field mappings, destination identifiers, and persistence permissions. Correct the plan and validate it again. An inspected or failed job is not a published dataset.
Generated links point at the wrong address
Set Server.UrlBase to the externally visible URL and configure the reverse proxy and optional base path consistently. Restart after changing server configuration. Browser-session checks can use the local origin even when published client URLs are wrong.
Requests are slow
Start with health/readiness checks and the relevant operation’s logs. Review paging, query limits, response-cache policy, tile-cache jobs, and remote-source latency. Enable OpenTelemetry or protected profiling deliberately; measure before increasing limits.
Get useful diagnostic evidence
Record the neoserver version, request path and method, status code, relevant configuration, and a minimal reproduction. Remove credentials and private source data before sharing logs in GitHub issues. Security-sensitive reports should follow the project’s security policy.