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.
Repeated failed password or Basic sign-ins return 429 with a Retry-After header. Five failures from one address, or fifty for one username across all addresses, start a block of 30 seconds that doubles with each further failure, up to 15 minutes. Wait for the block to pass; a successful sign-in resets it. See authentication.
Self-signed admin, editor, and viewer tokens are bound to one workspace. Tokens for these roles created by 0.1.2 or earlier are rejected; create replacements with create-token --workspace.
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.
A 403 when adding or testing a PostGIS store, or when changing its host or port, means the host is not listed in Datasource.DatabaseHosts. Ask a super administrator to add the store or to allowlist the host.
For file stores, verify that the path exists inside the container, is mounted, and matches the allowed-path policy. The native default allows only ./data/sources/** and ./data/imports/** (/data/sources/** and /data/imports/** in the container), so move files stored directly under ./data into ./data/sources or allowlist their location. 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.