Troubleshooting
This page covers the common ways Trove can look broken and what to check first.
If OIDC is enabled, use a browser session or TROVE_API_TOKEN for the API checks below. /healthz remains unauthenticated.
Check whether any agents exist:
curl http://SERVER:8080/api/v1/agentsCheck whether services exist:
curl http://SERVER:8080/api/v1/servicesIf agents are empty, no agent has successfully pushed.
If agents exist but services are empty, the agent may be collecting zero hosts/services.
The Trove token is wrong.
Fix:
docker compose exec server trove-server agent create AGENT_NAMEUpdate the agent with the new TROVE_TOKEN.
Remember: TROVE_TOKEN is the Trove token, not a Proxmox/Kubernetes/Docker credential.
From the agent host/container/pod, test:
curl http://SERVER:8080/healthzIf you used localhost, check whether that means the agent itself.
Use a LAN IP, DNS name, service name, or reverse proxy address reachable from the agent.
This is usually a Proxmox token permission issue.
Check:
- token user has
PVEAuditoron/ - token was created with
--privsep 0 - web UI privilege separation was unchecked
-
TROVE_PROXMOX_TOKENincludesuser@realm!tokenid=secret
Run:
PVE_TOKEN='trove@pve!trove-agent=PROXMOX_TOKEN_SECRET'
curl -sk -H "Authorization: PVEAPIToken=${PVE_TOKEN}" \
https://YOUR-PVE-HOST:8006/api2/json/nodesIf it returns {"data":[]}, the token authenticated but has no useful permissions.
If the agent card says platform docker when you expected Proxmox, you are running the wrong image.
Use:
ghcr.io/techdox/trove-agent-proxmox:latest
not:
ghcr.io/techdox/trove-agent-docker:latest
Check:
docker logs trove-agent-dockerConfirm the socket mount:
-v /var/run/docker.sock:/var/run/docker.sock:ro
If using a remote Docker endpoint, confirm DOCKER_HOST is correct.
Check logs:
kubectl logs deploy/trove-agent -n troveCheck:
- RBAC permissions
- namespace restrictions
- server URL from inside the cluster
- Secret values for
TROVE_TOKEN - network policies
Run:
trove-server alert testCompose:
docker compose exec server trove-server alert testIf the command says no channels are configured, the variables did not reach the server process.
For Compose, put alert variables under the server service, not the agent.
For systemd, put them in /etc/trove-server.env and restart trove-server.
If only one channel fails, check that channel's endpoint and credentials. Trove records successful per-channel deliveries while retrying only failed channels, so a temporary Discord failure should not duplicate a webhook that already succeeded.
Required:
TROVE_SMTP_HOSTTROVE_SMTP_FROMTROVE_SMTP_TO-
TROVE_DIGESTnot off
Also check SMTP port and auth.
Port 465 usually means implicit TLS. Port 587 usually means STARTTLS.
Possible causes:
- image has no digest reported by the agent
- registry requires credentials
- registry rate limit
- tag no longer exists
- registry blocks HEAD/GET in an unusual way
- freshness disabled
Check server logs for freshness errors.
For private registries, set TROVE_REGISTRY_AUTHS on the server.
A stale service usually means the agent is stale or offline.
Check:
curl http://SERVER:8080/api/v1/agentsThen check that agent's logs and network path.
If the server cannot start due to database issues:
- stop the server
- copy the database somewhere safe before experimenting
- inspect logs
- restore from backup if needed
Do not delete or overwrite the database unless you are intentionally resetting Trove.
Check that TROVE_OIDC_REDIRECT_URL exactly matches the provider callback and that the dashboard root is allowed as a post-logout return URI. For Authentik, both usually need to be allowed:
https://trove.example.com/oauth2/callback
https://trove.example.com/
See Authentication#troubleshooting for discovery, API redirect, and logout checks.
Trove
Read-only homelab service catalogue