Troubleshooting

Station stays offline

Check that the Python process is running with --listen, then verify its MQTT host and port, station ID, organisation ID, username, and password. Confirm the jig can reach the broker. If credentials were rotated, update the protected environment and restart the process.

Station connects but cannot fetch data

Check the station API base URL and HTF_API_KEY. A revoked key or a key for a different station cannot access that station's data. If a station secret was changed, restart or reconnect the station so it fetches the new value.

Runtime v0.3.0 keeps MQTT connected while retrying a failed managed-secret pull. An online station may therefore still lack a required secret. Check basic_station.secrets_pull_failed, the saved name, and the stage's required_secrets declaration. Plans with missing declared secrets stop before hardware executes.

Runtime YAML cannot be saved or applied

Read the configuration form's validation details. If it says Saved configuration needs correction, fix the existing plan and save a new revision. Check both the local file and exported runtime YAML with offline configuration validation, then confirm the station has pulled and applied the new plan.

A runtime expression prints literally

Add interpolate: true to the stage that uses ${dut_id}, ${run_id}, or a context expression. Runtime v0.3.0 defaults to literal strings. A missing reference on an interpolating stage fails that stage; check that an earlier stage produced the output.

A passed DUT has missing captured values

Check the report's capture warnings and the stage's explicit capture mapping. A failed source leaves unverified observations and does not update the DUT summary. Direct run_once() calls without a server run ID keep captures local; start a run through HTF to populate server history.

Inspect .htf-cache/report-outbox/<station-id>/rejected/ for the rejection reason, deferred/ for queued reports, and disk space/permissions if logs show report_storage_failed. Confirm the server supports HTF v0.1.4 before upgrading the runtime. Preserve pending files so the listener can retry them. See Capture DUT values.

Access controls or pool values are missing

Check the user's current project and station grants. A Viewer can inspect captured data but cannot start tests or read allocated/reserved ID-pool values. Custom permissions and other grants combine, and role changes affect live access. See Roles and permissions.

Run fails at a programming stage

Open the run's stage result and logs. Confirm the programmer is connected, its serial number and target device match the jig, and the configured firmware image and path exist. Try the equivalent hardware command on a bench only after preserving the original run evidence.

ID pool is exhausted or a value is reserved

Open DUT records & IDs to review available rows, reservations, and commits. A claimed linked row stays with its DUT after a failed run. Inspect that DUT and its assignment history, then retry with the same DUT ID after confirming whether any external service consumed the values.

Still stuck?

Keep the station ID, DUT ID, run time, first failing stage, and relevant log lines together when asking for help. Do not include passwords, API keys, or secret values. Contact Embeint if you need support.