Troubleshooting

Subject Group returns no data / "no subjects found"

The Subject Group Name field is case-sensitive and must match the name in EarthRanger exactly (see Subject Group). Double-check capitalization and spacing — e.g. elephants will not match a group named Elephants.

EarthRanger connection fails or times out

Verify the server URL, username, and password configured in the EarthRanger connection (see Data Source Connections). Confirm you can log into that same EarthRanger instance directly in a browser with the same credentials. Credentials aren't validated at setup time, so an invalid password only surfaces as an error once the workflow actually runs.

Google Earth Engine connection fails, or seasonal maps are missing

Confirm the service account private key (JSON) is valid and that the service account has been granted access to Earth Engine — see the Setup Guide. Seasonal Home Range, Dry/Wet Season Mean Speed rasters, and the Seasonal Windows CSV all depend on this connection; if NDVI retrieval fails, those outputs are skipped rather than failing the whole run.

Map Overlay / landDx doesn't load, or Protected/Unprotected maps are empty

By default the landDx geodatabase is downloaded from a Dropbox URL at runtime (see Map Overlay). If it's unreachable, switch to Custom Local File and point to a local GeoJSON/GeoPackage/GeoParquet file, or EarthRanger Spatial Feature if your protected areas are maintained there instead. Since this overlay also drives the Protected/Unprotected Home Range maps and the Protection Status Bar Chart, a failed or empty overlay will leave those outputs empty too.

Basemap tiles don't load, or the background map is blank

The Basemap Layers URLs are user-editable. If you changed either the ESRI World Hillshade or World Boundaries & Places layer away from its default, confirm the new tile URL follows the standard {z}/{y}/{x} template and is reachable from the machine running the workflow.

Elephant Sightings / Collaring Events map is empty

Check the Retrieve All Events settings — an Event Types filter that doesn't match any events in EarthRanger for the analysis period will return nothing. Leave it empty to include all event types. Also note that only events with point geometry are included by default; if your events use polygon geometry, keep Force Point Geometry enabled so they're reduced to a centroid instead of being dropped.

Report logo doesn't appear on the cover page

Check that the logo URL is a direct link to a PNG or JPG (not an HTML page), or that the local file path is reachable from the machine running the workflow. See Report Logo.

Movement Tracks / Subject Tracks / Home Range maps are empty or sparse

This is usually the Trajectory Segment Filter discarding most of the data. If the subject group moves unusually slowly or quickly, or has irregular fix intervals, the default Min/Max Speed and Min/Max Segment Duration thresholds may filter out nearly all segments. Loosen the bounds to match the study species' actual movement characteristics, then re-run.

Previous-period comparison is missing or looks wrong on the Movement Tracks map

Check the Previous Period mode — Preset defaults to "1 month back" but also offers "Same as current period" and other fixed lookbacks that use calendar boundaries rather than a rolling window. If you need a specific comparison window, use Calendar to pick an exact start date, or Custom to enter your own Years/Months/Weeks/Days offset.

Recursion Events raster and Mean Speed rasters are all too coarse or too slow to generate

All three rasters (Recursion Events, Dry Season Mean Speed, Wet Season Mean Speed) share one Step Length / Grid Size value — there is no way to set a finer grid for one without affecting the others. Lowering it below the default 2000 m makes all three more detailed but slower to generate and larger in file size.

Seasonal Home Range or Seasonal Mean Speed rasters are missing for some subjects

These outputs depend on NDVI-derived wet/dry season windows from Google Earth Engine (see seasonal_windows.csv in the output directory). If GEE returns no usable NDVI signal for the analysis period or region, season labelling can't proceed and season-dependent outputs are skipped for the affected subjects.

Protection Status Bar Chart is empty or looks wrong

This chart is derived from the same protected/unprotected classification as the Protected and Unprotected Home Range maps, based on the selected Map Overlay. If the overlay layer doesn't cover your study area, every fix will be classified the same way (typically "Unprotected"), skewing or emptying the chart.

No outputs written / can't find results

All outputs are written to the directory specified by the ECOSCOPE_WORKFLOWS_RESULTS environment variable. Confirm it's set and points to a directory the workflow process can write to.

Generated files differ from committed files in ecoscope-workflows-ste-general-workflow

The generated workflow directory is out of sync with spec.yaml. Run the recompile script locally and commit the result:

pixi run --manifest-path pixi.toml --locked bash -c "./dev/recompile.sh --update"

Found wildcard version (*) in requirements or Found local file channel (file://) in requirements

In spec.yaml, every dependency under requirements must pin an exact version and use a remote conda channel — wildcard versions and local file:// channels are only valid for local development, not for CI using published packages.

VERSION.yaml (...) must be greater than main branch (...)

Bump MAJ/MIN/PATCH in ecoscope-workflows-ste-general-workflow/VERSION.yaml so it's strictly greater than the version on main before opening or updating a PR.

test-cases.yaml must contain at least one test case

Every workflow requires at least one top-level entry in test-cases.yaml with a params block. See the existing entries in that file for the expected format.

Workflow tests fail in CI but pass locally (or vice versa)

test.yml runs test cases against all of ubuntu-latest, macos-latest, and windows-latest, and relies on the EarthRanger and Earth Engine secrets being available to the workflow run. If a test only fails on CI, check whether it depends on a secret or on OS-specific path handling.