Troubleshooting

Agent does not show up in the app

1. api_url must be https://<app-host>/api/v1. The agent appends /sync/.
2. The token starts with wgf_ and has not been revoked.
3. From the agent host: curl -I "$API_URL/health/" (expect a platform response).
4. In the UI: Test now. unauthorized / forbidden — token; unreachable — DNS, firewall, or wrong URL.

Online, but the catalog is empty

An agent without plugins sends a heartbeat with resources: []. Install a plugin and set enabled: true on a source. wg-flow-agent dry-run prints the JSON that would be posted.

Offline after 5 minutes

The app marks an agent offline when last_seen_at is older than 5 minutes. Confirm run is alive and that the scheduler heartbeat (scheduler.sync_interval_seconds) is firing.

401 on sync after revoking a token

Create a new token, set tenant_token, save the YAML. A previous wgf_… cannot be recovered.

Plugin install fails

plugin marketplace list must see the catalog. The agent uses the same api_url / token as sync (marketplace sits behind the gateway). In the pilot the wheel must be uploaded in the staff admin.

UI “Failed to fetch”

The UI is bound to a different interface than the one you opened. In Docker set WGFLOW_UI_HOST=0.0.0.0 and open http://127.0.0.1:8765 on the published port.