Troubleshooting

Startup

Symptom	Source-backed checks
POSTGIS_DATABASE_URL or DATABASE_URL is required	Set a metadata DSN with a database name.
invalid DATABASE_URL	URI form needs host and database path; libpq form needs dbname= or database=. Remove malformed outer quotes.
postgres ping failed	Check host, port, credentials, PostgreSQL availability, and effective SSL mode. prefer is rewritten to disable.
schema migrate	Metadata role needs DDL privileges and schema access.
auth: central auth database URL is not configured	Set POSTGIS_AUTH_DATABASE_URL, CENTRAL_DATABASE_URL, or DATABASE_URL.
Auth DB ping failure	Verify Central DSN and connectivity; startup is fatal.
Template parse fatal error	Ensure the complete web/ tree and partials are in the working or executable directory.

Authentication and routing

Symptom	Cause/check
Redirect loop or wrong login host	Set POSTGIS_PORTAL_LOGIN_URL; verify forwarded proto/host.
authentication unavailable / 503	Check auth DSN and Central dashboard_sessions/dashboard_users schema.
Permission denied	Grant the user's Central group view, edit, or admin on service resource postgis_service.
Bearer token receives 401	PAT storage is not wired into this service; use acugis_session.
Prefixed links or assets fail	Align BASE_PATH, X-Forwarded-Prefix, and Apache proxy mode.
WebSocket upgrade fails	Enable proxy_wstunnel, put WS proxy rules first, and verify Origin matches forwarded/request host.

Connections and settings

Symptom	Cause/check
Connection password decrypt error	POSTGIS_SECRETS_KEY differs from the key used to encrypt stored values or is malformed.
PostGIS test reports disabled	PostGIS_Version() failed or extension is absent; errors from that query are intentionally treated as not enabled.
Setting rejected	Only the documented allowlist is editable; validate units, enum, integer, and timeout syntax.
pending_restart remains true	The service reloads configuration but does not restart PostgreSQL.
HBA path not configured	Set connection hba_file_path or POSTGIS_HBA_FILE.
HBA read/write failure	The service operates on its own filesystem; a path on a remote PostgreSQL server is not remotely edited.

Applying HBA rules creates <pg_hba.conf>.bak-YYYYMMDD-HHMMSS, replaces/appends only the marked managed block, then calls pg_reload_conf(). On reload failure, inspect the returned backup path; restoration is manual.

Jobs, backup, restore, and import

Symptom	Cause/check
Job remains queued	Confirm worker process is running and metadata DB is writable. It handles one job per two-second tick.
Cancel returns 409	Only queued jobs can be cancelled.
Job repeats after restart	Every running job is requeued at startup; age is not considered. Check remote state before retrying.
pg_dump/pg_restore not found	Install PostgreSQL client tools in the service PATH.
Backup artifact empty/missing	Check target directory ownership, disk space, command output in job error, and managed-server connectivity.
Restore path rejected	Use an artifact path below POSTGIS_BACKUP_DIR, normally from the backups listing.
ogr2ogr/ogrinfo failure	Install GDAL, verify supported extension/layer, and inspect error_message.
Upload rejected	Use multipart field file, a supported extension, and body no larger than 512 MiB.
Source path rejected	Import sources must be below POSTGIS_IMPORT_DIR (or system temp internally).
Clone fails	Source and target must share one connection; active source sessions are terminated before template cloning.

Failed create/clone jobs can leave registry rows with failed status. The API has no endpoint to remove only such a registry row without queuing a remote drop; reconcile cautiously.

Terminal

Symptom	Cause/check
psql terminal fails	Install psql; verify selected connection/database, PTY support, and stored credentials.
Logs terminal fails	journalctl must exist and the process must read the postgresql unit.
Server command rejected	Only the documented exact command forms are allowed; metacharacters are forbidden.
systemctl command denied	Configure host permissions for the service identity; no escalation is built in.
Session closes	Idle timeout is 30 minutes; maximum lifetime is eight hours; log reads use 60-second deadlines.

Logs

With the supplied unit:

sudo journalctl -u postgis-service -f
sudo journalctl -u postgresql -f

There are no configurable log levels or request access logs. Terminal audit lines begin terminal audit: and include username, terminal kind, action, and detail.