Troubleshooting

Workflow errors out with no current-period events found

The current-period event fetch sets raise_on_empty: true, so if EarthRanger has zero hwc_lvstprd events for your selected time range, the workflow raises an explicit error. Widen the time range or confirm the events exist under that event type in EarthRanger. The previous-period fetch sets raise_on_empty: false — a comparison period with no events is expected and handled gracefully (the historic chart branch is simply skipped for that ranch).

EarthRanger connection fails or times out

Verify the server URL, username, and password configured in the EarthRanger Connection. 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.

Almost everything is empty even though EarthRanger has predation events

Two filters run before any chart, map, or table is built: events must have Ranch exactly matching Eselengei, Mbirikani, or Kimana, and "Validity of claim" exactly equal to "Valid". If your EarthRanger event form uses different ranch names, different capitalisation, or a different claim-validity label, those events are silently dropped rather than causing an error — check the raw event details for spelling/casing mismatches.

Amboseli geospatial layers or the Word template fail to download

The three Amboseli GeoPackages and the Word report template are fetched from fixed Dropbox share links in spec.yaml. These links carry an expiring share token (st= parameter); if a link has been rotated or revoked on Dropbox's side, fetch_and_persist_file will exhaust its 3 retries and fail. This isn't a workflow configuration issue — the URLs in spec.yaml would need to be refreshed.

Historic comparison chart is missing for one or more ranches

The historic chart is built per ranch from the zipped current + previous period partitions. If a ranch has no previous-period events (or no current-period events) after filtering, that ranch's chart is skipped — the other ranches' charts still render normally. This is expected fan-out behaviour, not a workflow-wide failure.

Historic chart's confidence band looks too wide or too narrow

The band is a 95% CI around the historic mean (band_method: ci_mean, band_level: 0.95), computed per Animal responsible facet from whatever previous-period data your Previous Period selection produced. A short or sparse comparison window produces a wide, low-confidence band — widen the Previous Period offset (e.g. switch Custom to a larger number of months, or choose a Preset further back) for a more stable estimate.

A predator, boma type, claim type, ranch, or livestock-species value is missing from a chart, or renders in a fallback colour

Every colour-mapped category (see the Technical Guide's Colour Mapping section) has an explicit hex colour; any value not in that mapping falls back to a pale default (#f0f8ff), and keep_unmapped: false means unmapped rows can be dropped entirely rather than shown with the fallback. If a chart is missing a category you expect, check whether the underlying EarthRanger field uses a value not covered by the workflow's colour mapping.

Livestock killed total doesn't match manual counting

total_animals_killed is computed as total_adult_livestock_killed + total_young_livestock_killed, where each of those is itself a fallback-combined value (a primary detail field, falling back to a secondary field if the primary is null, then to 0). If an event has values in both the primary and fallback fields, only the primary is used — check which field a given event actually populated in EarthRanger.

Per-ranch output files are named "Eselengei", "Mbirikani", "Kimana" instead of something more descriptive

This is expected — the per-ranch summary tables are persisted with the ranch name itself as the filename (e.g. a GeoParquet file literally named Eselengei), not a compound name like overall_predation_summary_Eselengei.

Map PNG is blank, cut off, or missing in the Word report

All three maps wait 40 000 ms for the basemap tiles to load before capturing the screenshot — far longer than the 1–10 ms wait used for the Plotly charts, which render client-side without external tile requests. On a slow network this can still be insufficient for a consistently complete tile render.

Word report is missing an image, or fails to generate

generate_pcf_report runs with validate_images: true, which checks that every expected chart/map image exists before populating the template. If any upstream chart or PNG conversion failed or was skipped (e.g. due to an empty ranch partition), report generation will fail rather than produce a document with blank placeholders.

Word report always says "Generated by Ecoscope"

This is expected — generated_by is a fixed string in spec.yaml, not looked up from the EarthRanger user who ran the workflow.

Dashboard has fewer than 24 widgets, or a ranch is missing from a merged widget

Two widgets on the dashboard — Historic Predation Trend by Ranch and Predation Summary by Ranch — are merged multi-view widgets built from the same per-ranch fan-out described above. If a ranch had no data for one branch, that ranch's view is simply absent from the merged widget rather than the whole widget failing.

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.

ecoscope-workflows-bl-pcf-report-workflow/ is missing from your checkout

This generated directory is tracked in git but can be absent from a local working tree (e.g. after a partial checkout or an interrupted recompile). Regenerate it before committing anything:

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

Generated files differ from committed files in ecoscope-workflows-bl-pcf-report-workflow

The generated workflow directory is out of sync with spec.yaml. Run the recompile script locally and commit the result (same command as above).

test-cases.yaml references a calculator task that doesn't exist in this workflow

The current test-cases.yaml still contains calculator parameters (a, b, operation) left over from the workflow scaffold — spec.yaml has no task with that id. If you're updating test cases, replace these with parameters for the tasks this workflow actually exposes (workflow_details, time_range, er_client_name, the previous-period offset, and time_frequency).

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-bl-pcf-report-workflow/VERSION.yaml so it's strictly greater than the version on main before opening or updating a PR.

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. If a test only fails on CI, check whether it depends on EarthRanger credentials being available as secrets, or on OS-specific path handling.