My collector deployed but no data is landing¶
Applies to: every collector deployed through deploy_collector or the webapp Deploy panel · First check: collector_health
The single most common surprise: deploy_collector does not run a collector. It
registers the service and mints an agent JWT — nothing streams until you run the
agent with that token. This page explains that step and the states you see while
data starts (or fails) to land.
Bring-your-own, by design
deploy_collector is remote bring-your-own only. It returns a service_id, a
binding_id, a gateway_url, and a token (the agent JWT). The overseer never
spawns a platform-managed container from this tool. See
deploy_collector and
Worked examples → Flow 1.
Run the agent¶
The collector produces data only once the aetelier-agent process is running against
the gateway with the JWT from your deploy result. The two load-bearing variables:
| Env var | From | Notes |
|---|---|---|
AETELIER_GATEWAY_URL |
the gateway_url in the deploy result |
Match the scheme exactly — see TLS vs plaintext |
AETELIER_TOKEN |
the token in the deploy result |
The agent JWT. Required — the agent does not self-sign |
The token's claims already carry binding_id, service_id, and session_id, so you
do not set those as separate variables — the agent extracts them at startup. Full contract:
aetelier-agent → Environment variables.
The webapp shows the exact command for your binding, on the Deploy panel or from the fleet's COMMAND button:
docker run -d --pull always --restart unless-stopped --name aetelier-agent-<exchange>-<datatype>-<binding4> \
-v "$HOME/aetelier-data:/home/agent" \
-e AETELIER_GATEWAY_URL="<gateway_url>" \
-e AETELIER_TOKEN=<token> \
-e RUST_LOG=info \
ghcr.io/aetelierxyz/aetelier-agent:latest
The container name is aetelier-agent- plus the exchange id, the datatype, and the
first four characters of the binding_id; see
aetelier-agent → Deployment.
Treat the JWT like a password — keep it out of shared configs and version control.
Starting vs silent — read the verdict¶
Once the agent is up, collector_health returns a
top-line verdict. A fresh, working deploy reads starting, not a failure, until the
first rows land:
| Verdict | Means | Do this |
|---|---|---|
starting |
Connected; still inside the first-data grace, no rows yet | Wait out the grace, then re-check |
healthy |
Connected and fresh rows are landing | Nothing — data is flowing |
degraded |
Connected but rows stalled past the grace | Check the venue/symbol and the agent logs |
silent |
Not connected, or no data and past grace | The agent is not running or cannot register — see below |
liveness.connected: false means the agent never registered with the gateway.
liveness.connected: true with landing.rows_last_5m: 0 past the grace means it
registered but is not producing — usually a wrong symbol or a paused task.
The first-data grace (~180s)¶
A new deploy has no lake rows for the first few minutes, so health leads with liveness
and reads starting rather than reporting a problem. The window is the platform's
first-data lag, 180 seconds; it is what separates starting from degraded. The
health result reports landing.expected_first_data_by — do not conclude failure
before that timestamp.
The binding stays pending¶
If the binding never leaves pending and the agent seems stuck connecting, the agent is not registering with the gateway. Common causes:
- TLS vs plaintext mismatch. The most frequent cause. A gateway served behind a
TLS-terminating origin needs an
https://AETELIER_GATEWAY_URL; a plaintext h2c gateway needshttp://. Pointing a plaintext agent at a TLS origin (or the reverse) leaves the agent connecting with the binding never activating. Match the scheme to how the gateway is actually served. - Expired or wrong-key token. A JWT that has expired, or was minted against a signing key the gateway no longer uses, is rejected at registration. Mint a fresh token from the webapp Deploy panel.
- Binding already in use. The same
binding_idis already held by another active agent. Stop the other agent or deploy a new collector.
The agent's own diagnostics for these are in
aetelier-agent → Common operational issues.
One collector, one symbol¶
A collector carries exactly one symbol. Deploying with more than one symbol is rejected at admission — deploy a separate collector per symbol. If a deploy you expected to accept several symbols came back refused, this is why.
Quick checklist¶
- Did you actually run the agent?
deploy_collectoralone mints only a JWT. - Is
AETELIER_TOKENthe exacttokenfrom the deploy result, unexpired? - Does
AETELIER_GATEWAY_URLmatch the gateway's scheme (http://vshttps://)? - Are you inside the ~180s grace? Check
landing.expected_first_data_by. - Is the symbol the venue-native form? Confirm with
list_cex_options. - One symbol per collector.
Related¶
collector_health— the verdict and landing detailaetelier-agent— the run contract, JWT handshake, and lifecycle- Worked examples → Flow 1 — deploy and watch data land, end to end
- Units and the 402 error — if the deploy itself was refused for balance
- Getting help — when to escalate