Debug & Troubleshoot

GeoEngine provides a set of CLI commands to inspect workers, read container logs, and repair broken state. This guide covers the most common debugging scenarios.

Check What Has Changed

Before re-applying a worker, use geoengine diff to see which tracked files have changed since the last apply:

# Check tracked files: geoengine.yaml, Dockerfile, and build-relevant worker files
geoengine diff

This is useful for confirming which changes will be picked up when you run geoengine apply next.

Inspect Registered Workers

List all registered workers and their current status:

# Summary view
geoengine workers

# Expanded view — shows all versions as sub-rows beneath each worker
geoengine workers --all

The output table includes the following columns:

Column	Description
ID	Worker UUID used by the CLI and Docker tags
NAME	Worker name
LATEST TAG	Most recently applied local tag plus the total number of applied tags, e.g. `claude-1.0.0 (3)`
LAST APPLIED	Relative time since last apply (e.g. `3 min 42 s ago`)

If a worker is missing from this list after geoengine apply, run geoengine patch to repair the worker registry (see below).

Inspect a Specific Worker

Get detailed information about a single worker:

# Show the latest applied version, config hash, and available versions list
geoengine describe

# Show info for a specific previously-built tag
geoengine describe --tag claude-1.0.0

The output includes:

Name and description
Version and applied at timestamp
Config hash — a SHA-256 of the applied config; useful to confirm two builds used the same configuration
Applied tags — all local tags currently on disk for this worker
Runtime image — the base runtime image used when the tag was applied, when available

Read Container Logs

Container logs stream to stderr automatically when you run a worker. To separate logs from the structured result, use --json mode:

geoengine run --actor CLI --json --input input-file=/path/to/file.tif

stderr — container log output, streamed in real time
stdout — the final JSON result, printed on completion:

{
  "job_id": "01HX4V2Z9B2F4T8H6P9K3N7Q1M",
  "status": "completed",
  "exit_code": 0,
  "files": [
    {
      "name": "output.geojson",
      "path": "/path/to/output/file",
      "size": 1024,
      "kind": "output"
    }
  ]
}

A non-zero exit_code means the container script exited with an error. Check stderr for the Python/R traceback.

Inspect Run History

Every geoengine run is saved locally by default, with metadata and compressed streamed logs under ~/.geoengine/runs/<worker_id>/<job_id>/. Use the job_id from the JSON result to inspect the run later:

geoengine worker runs show <job-id> --json
geoengine worker runs logs <job-id> --stream stderr --tail 100

Use geoengine run --no-history for sensitive or ephemeral runs that should not be written to local history.

Debug Worker Tests

If geoengine test fails, rerun the failing case with logs and keep the output folder:

geoengine test --case <case-name> --verbose --keep-workdir

Inspect .geoengine-test/<case-name>/ to confirm what the worker actually wrote. If the output is correct but the comparison failed, update the expected file, tolerance, or ignored JSON paths in tests/geoengine.test.yaml.

Force a Clean Rebuild

If your Docker image is stale or a dependency change isn’t being picked up, force a full rebuild with --no-cache:

geoengine apply --no-cache

This bypasses Docker’s layer cache and rebuilds the image from scratch. Use it when:

You’ve updated a package version in pixi.toml but the old version is still being used
The image is in an inconsistent state after a failed build
You want to confirm the image builds cleanly from the current config

Repair GeoEngine Artifacts

geoengine patch performs a maintenance sweep and repairs any broken state across all GeoEngine-managed artifacts:

geoengine patch

Run this after upgrading GeoEngine, or whenever workers, plugins, or agent skills are behaving unexpectedly. It checks and repairs:

Global registry (~/.geoengine/settings.bin) — validates the settings file
Worker state files — validates state/*.json, reports orphaned records
Config snapshots — validates saves/<worker>/map.json, checks all referenced snapshots exist
GIS plugins — reinstalls stale or missing plugin files for QGIS and ArcGIS Pro
Agent skills — syncs skill files into each installed agent’s skills folder; files with matching SHA-256 hashes are skipped

geoengine patch exits with a non-zero status if any validation issue is found, making it safe to use in scripts.

Delete a Worker or Version

If a worker is in a broken state and needs to be removed:

# Delete a worker entirely by ID (shows a confirmation prompt)
geoengine delete --id <worker-id>

# Delete the worker in the current directory
geoengine delete

# Delete a specific tag only (removes image, mapping, and snapshot)
geoengine delete --tag claude-1.0.0

After deleting, re-apply the worker with geoengine apply to recreate it cleanly.

Common Issues

Build fails: `command.script` not found

Make sure the script path in geoengine.yaml is relative to the worker directory and the file actually exists there.

`geoengine apply` rejects my version number

In production mode, the version in geoengine.yaml must be a valid semantic version (MAJOR.MINOR.PATCH) and must be greater than or equal to the highest version already recorded. Use geoengine apply --dev to skip this check during development.

Worker appears in `geoengine workers` but not in QGIS/ArcGIS

Run geoengine patch to reinstall any stale plugin files, then close and reopen the GIS Processing Toolbox to refresh the worker list.

Dependency changes not reflected after apply

Run geoengine apply --no-cache to force a full Docker rebuild. Docker may be using a cached layer that predates your pixi.toml changes.

​Check What Has Changed

​Inspect Registered Workers

​Inspect a Specific Worker

​Read Container Logs

​Inspect Run History

​Debug Worker Tests

​Force a Clean Rebuild

​Repair GeoEngine Artifacts

​Delete a Worker or Version

​Common Issues

​Build fails: command.script not found

​geoengine apply rejects my version number

​Worker appears in geoengine workers but not in QGIS/ArcGIS

​Dependency changes not reflected after apply