Skip to content

Troubleshooting

Service starts with authentication disabled

Look for central auth disabled or central auth unavailable. Set a reachable PostgreSQL URL in QGIS_AUTH_DATABASE_URL, CENTRAL_DATABASE_URL, or DATABASE_URL and confirm the Central tables in Database exist. The process intentionally continues without auth, so a running process is not proof that access control is active.

Database-backed APIs return unavailable

Registry stores are created only after a successful Central connection and schema initialization. Check startup messages for each runtime dataset, basemap, browser map, ingest, and metadata schema. Verify DDL privileges and PostgreSQL features such as JSONB, arrays, UUID columns, and GIN indexes.

Operational import rejects the admin DSN

RUNTIME_PG_ADMIN_DSN is parsed only as a postgres:// or postgresql:// URL. The tracked env sample's libpq key/value format is incompatible with current source.

Use a redacted URL form:

postgres://admin:[REDACTED]@127.0.0.1:5432/postgres?sslmode=require

Then verify database/role creation privileges, PostGIS availability, ogrinfo/ogr2ogr on PATH, writable RUNTIME_DATASETS_ROOT, and writable PG_SERVICE_FILE. A failed import may leave a database, role, service entry, or partial data requiring manual cleanup.

QGIS returns 404 or cannot open a project

  • Confirm PROJECTS_ROOT/<id>/.qgis-publish.json and its referenced .qgs exist.
  • Ensure QGIS_MAP_PATH_PREFIX matches the path visible to QGIS Server, not merely the main process.
  • Ensure QGIS Server can read project/data files and the same pg_service.conf.
  • If QGIS_MAPSERV_BIN is set, verify it is executable and its libraries/plugins are available to the systemd service.
  • Otherwise test QGIS_MAPSERV_URL directly.
  • Review [wms-map-path], [wms-proxy], and QGIS stderr logs.

PostGIS layers fail while file layers work

The API's PG_SERVICE_FILE and QGIS Server's PGSERVICEFILE must refer to the same content. The repository does not configure the QGIS Server process. Check file path, permissions, service section, network reachability, SSL mode, and database grants. Protect the file because it contains plaintext passwords.

Raster generation fails

Verify:

  • PYTHON_BIN imports QGIS modules;
  • CREATE_QGIS_PROJECT_SCRIPT exists;
  • QGIS_PREFIX_PATH and QT_QPA_PLATFORM=offscreen suit the host;
  • gdalinfo or GDALINFO_BIN works;
  • the project root is writable.

The generator's combined output is included in the server error and journal.

qcarta cannot reach QGIS

QGIS_SERVER_URL has no source default. Set a complete reachable URL and test QGIS capabilities from the qcarta service identity/network namespace. /api/health only proves the qcarta process responds.

Tiles are stale or never cached

  • Confirm QCARTA_DISABLE_CACHE is not 1.
  • Confirm QCARTA_CACHE_DIR exists, is writable, and has free inodes/space.
  • Check QCARTA_CACHE_TTL is an integer number of seconds.
  • Compare project/map/layer/filter parameters; all render-affecting dimensions contribute to keys.
  • Use QCARTA_CACHE_DEBUG=1 briefly, then disable it because logs can disclose filters and paths.
  • For purge, configure the same QCARTA_CACHE_PURGE_TOKEN in both processes.

Metadata cache entries do not currently apply the normal cache TTL. Purge/re-prewarm them after project changes if automatic invalidation did not occur.

Metatile seams or rendering errors

Try safe mode:

QCARTA_DISABLE_METATILES=1

Equivalent settings are size 1 and buffer 0. Otherwise tune QCARTA_METATILE_SIZE and QCARTA_METATILE_BUFFER. Oversampling increases upstream render cost; return QCARTA_TILE_OVERSAMPLE to 1 while isolating a problem.

Seed job disappears

Seed state is memory-only and is lost on qcarta restart. Jobs are not shared across instances and have no durable queue. Resubmit after confirming the process is stable. Requests above 300,000 tiles are rejected.

Browser UI is incomplete offline

The HTML references public CDNs, map providers, Google Fonts, and epsg.io. Check browser developer tools and Content Security Policy. Vendor dependencies if outbound browser access is not acceptable; no vendoring build is supplied.

systemd reports read-only filesystem

The main unit uses ProtectSystem=strict. Add configured writable roots to ReadWritePaths, including versions, runtime datasets, thumbnails, and PG_SERVICE_FILE where used. Ensure ownership/group permissions match www-data. The qcarta cache also needs a writable location.

Base-path redirects or static assets are wrong

Set BASE_PATH to the externally visible prefix without a trailing slash and configure the reverse proxy to preserve that mapping. Confirm UI_ROOT and FEDERATION_SHARED_UI_ROOT. Test both the bootstrap script and /shared/ui/ assets beneath the prefix.

Logs

journalctl -u qgis-publish-service -f
journalctl -u qcarta-tiles -f

Relevant prefixes include [resource-sync], [forms-parser], [legend-*], [prewarm], [wms-proxy], [getmap-cache], [CACHE], [TILE DEBUG], [METATILE_*], and [SEED]. Logs are text, not structured telemetry; the repository contains no tracing or external metrics exporter.