Troubleshooting¶

Logs and first checks¶

Foreground logs go to stdout/stderr; the parent systemd unit sends both to the journal. GeoServer/ESRI job details are in geoserver_jobs.error_message and log_text. Apache uses its configured access and error logs.

systemctl status geovault
journalctl -u geovault -b -e --no-pager
ss -ltnp | grep 8085
sudo -u www-data sh -c 'command -v ogrinfo ogr2ogr gdalinfo gdal_translate gdalwarp'
curl -i http://127.0.0.1:8085/api/discovery

An unauthenticated API response is not a health contract. GeoVault provides no health, readiness, or metrics endpoint.

Startup and installation errors¶

Symptom or log	Check
Build cannot resolve module `shared`	Build inside the federation tree; `../shared` must exist because of the local `replace` directive.
`database: ... check DATABASE_URL`	A non-empty metadata DSN is malformed/unreachable, PostgreSQL rejected it, or migrations lack `CREATE`. Remove `DATABASE_URL` only when JSON metadata mode is intentional.
`auth: ... set GEOVAULT_AUTH_DATABASE_URL...`	None of `GEOVAULT_AUTH_DATABASE_URL` → `CENTRAL_DATABASE_URL` → `DATABASE_URL` selected a reachable Central auth database.
Fatal template parse	Install all of `web/`; templates try CWD and then the executable directory.
`/shared/ui/*` returns 404	Install shared UI assets or set `FEDERATION_SHARED_UI_ROOT`; check its exact search precedence in configuration docs.
Static files 404 while templates work	The static file server uses CWD-relative `./web`; verify systemd `WorkingDirectory=/opt/geovault`.
Unit cannot execute or write	Check binary mode/architecture, `www-data` ownership, `/data/projects`, `/opt/geovault/data`, JSON path, temporary directory, and systemd `ReadWritePaths`.
Port already in use	`:8085` is fixed. `GEOVAULT_LISTEN` is unused and cannot move the listener.

Authentication and authorization¶

Symptom	Likely cause
Browser redirects to `/login`	Missing, expired, or invalid `acugis_session`; Central login route unavailable.
API `401`	No valid session cookie. Shared auth can parse Bearer PATs, but GeoVault's auth provider does not supply a token store, so PAT authentication is unsupported here.
Login loop or cookie not sent	Wrong host/domain, HTTP instead of HTTPS, inconsistent `ACUGIS_SESSION_COOKIE_DOMAIN`, or proxy cookie/path handling. Prefer host-only cookies unless cross-subdomain sharing is required.
`403` permission page	User groups lack the required `geovault` service `view`, `edit`, or `admin` ACL.
Dataset `403 permission required`	User groups lack the requested `geovault_dataset` permission.
`503 authentication unavailable`	Central auth database query/connectivity failure.

Confirm Central works on the same external origin, Apache routes /login and /logout, and X-Forwarded-Proto is exactly https.

Database and catalog errors¶

Symptom	Check
`sslmode=prefer mapped to sslmode=disable`	This is source behavior. Use `sslmode=require` or stronger when TLS is mandatory.
`libpq string is missing dbname=`	Quote a keyword DSN containing spaces in the systemd environment file, or use a no-space PostgreSQL URI.
Migration/FK errors	Metadata DB needs schema privileges and compatible Central tables such as `dashboard_users`.
`dataset registry requires DATABASE_URL`	The feature needs metadata PostgreSQL; JSON mode supports only the versions catalog.
Catalog starts empty	Verify `DATABASE_URL` selection or the JSON path precedence and service read permission.
JSON save/rename failure	Verify parent-directory write permission, free space, and that only one GeoVault process writes the catalog.
Lost or inconsistent versions	Multiple processes can race whole-table/whole-file replacement; stop extra writers and restore a consistent backup.

Never paste DSNs or /etc/geovault.env into tickets. The tracked deploy draft contains a credential-like sample; rotate it if it has ever been used.

GDAL, storage, and imports¶

Symptom	Check
`executable file not found`	All five GDAL/OGR commands must be on the systemd service `PATH`, not only the interactive shell's path.
Metadata/preview/transform failure	Run the reported `ogrinfo`, `gdalinfo`, `ogr2ogr`, `gdal_translate`, or `gdalwarp` operation as `www-data`; inspect format drivers and file permissions.
Upload/import permission denied	Dataset storage is hard-coded below `/data/projects`; `GEOVAULT_DATA_DIR` does not relocate it.
URL/S3 import stops near 500 MiB	Adjust `GEOVAULT_IMPORT_MAX_BYTES` and operator-supplied proxy limits; the default is 524288000 bytes.
URL import times out	`GEOVAULT_IMPORT_HTTP_TIMEOUT` defaults to `15m`; also inspect DNS, firewall, certificates, and remote response.
Temporary-space exhaustion	Imports, extraction, clips, and GDAL use the OS temporary area; monitor `/tmp` under the parent unit.
Browser map or styling is blank	Check browser CSP/network access to cdnjs, unpkg, Google Fonts, and CARTO, or vendor the assets.

Proxy and publication failures¶

Symptom	Check
Apache 502	Unit is down, port 8085 is blocked locally, or upstream mapping is wrong.
`/geovault` works but links/assets 404	With the checked-in prefix-stripping Apache mapping, leave `BASE_PATH` empty and set `X-Forwarded-Prefix: /geovault`.
Direct and proxied routes disagree	Do not combine a stripped upstream prefix with `BASE_PATH=/geovault`; verify the actual path Apache sends upstream.
Mixed-content/Secure-cookie issue	Terminate TLS at Apache and send `X-Forwarded-Proto: https`; GeoVault has no native TLS.
Raster publish fails	Set and reach `QGIS_PUBLISH_URL`; verify forwarded caller authentication and QGIS service logs.
Project history fails while publish works	Check `QGIS_PUBLISH_BASE_URL` or its derivation from `QGIS_PUBLISH_URL`.
Vector publish fails	Check `TILESERVER_REGISTER_URL`; its empty default is `http://localhost:8081/register`.
PostGIS Service calls fail	Check `POSTGIS_SERVICE_URL`, metadata tables, network access, and matching `POSTGIS_SECRETS_KEY`.
GeoServer private URL rejected	Only literal RFC1918 IPv4 is enabled by `GEOVAULT_GEOSERVER_ALLOW_PRIVATE=1`, `true`, or `yes`; link-local/metadata targets remain blocked.
GeoServer password decrypts incorrectly	Restore the original valid key. Missing/invalid keys make new passwords use `plain:` storage.
Job remains `running` after restart	Jobs run in-process and have no recovery worker or resume API; investigate, mark/clean up under an operator procedure, then resubmit.

SELECT id, job_type, status, error_message, updated_at
FROM geoserver_jobs
ORDER BY id DESC
LIMIT 20;

Docker/Compose, Nginx, native TLS, scaling, and health-check configurations are not provided or verified. Diagnose any operator-supplied configuration against its own runtime and proxy logs.