Troubleshooting

The chart is empty

With source: nothing appears until an agent's first event arrives. Check that you push into the same stream object you pass as source.
With agents and the ref: updateAgent and push ignore ids that aren't in agents (or added by the source), with a one-time console warning. Check the ids match exactly.
The ref is null until the chart mounts. Call it as ref.current?.push(…), after mount.

The chart starts over on every render

A new source object resets the chart's stream data. connectSse('/api/agents') or createAgentStream() written directly in a component body creates a new one each render. Use useAgentStream(), useMemo(() => connectSse(url), [url]), or a module-level stream.

A flat line at 0% or 100%

The chart is plotting progress. Since 0.6.0 the default metric="auto" plots progress only once every visible agent reports it. If you set metric="progress" (or report progress once and never again), switch to metric="tokens" or keep progress current.

A stall alert during a tool call

The detectors only see output and status. A tool call reported as active looks like a stall after 10 seconds. Report waiting while tools run: with events, tool-start and tool-end do it for you; with samples, send { status: 'waiting' }. See Limitations.

Lines jump or appear in the wrong place in time

Event time (and since) must be in the performance.now() clock of the page or process that pushes. Timestamps from Date.now() or from another machine land in the wrong place. Leave time out to stamp events on arrival, or use the SSE adapter, which converts times between machines.

"Functions cannot be passed to Client Components" or a server import error

The main entry @dan-build/agentstat is client-only. Render AgentStat from a client component (or import it into a server component and pass only serializable props), and import server code from @dan-build/agentstat/sse or an adapter entry. Callback props like onAnomaly need a client component.

The SSE connection drops or never connects

Buffering proxies (nginx, some CDNs) hold back event streams. createSseHandler already sends X-Accel-Buffering: no and Cache-Control: no-cache, no-transform; if events still arrive in bursts, something in front ignores them. Set proxy_buffering off (nginx), turn off compression for text/event-stream, and check for a compression middleware in front of the route.
Idle timeouts: the handler sends a comment every 15 seconds (heartbeatMs). Lower it if a proxy closes connections sooner.
Serverless or several replicas: each instance has its own stream, so a browser connected to one doesn't see agents running on another.
Reconnects resume where they stopped, as far back as the server keeps (5 minutes), so a short drop loses nothing.

The shadcn components fail to compile

The registry components import AgentTelemetry, useAnomalyAnnouncer and timelineBars, which arrived in 0.6.0. shadcn add installs @dan-build/agentstat@^0.6.0, so a missing export usually means the install went elsewhere (another package of a monorepo) or didn't finish: run npm install @dan-build/agentstat@latest in the app's own package. If you copied the components before a library update, add them again to pick up changes.

Health stays below 100

tokenEfficiency compares the rate with a 5–25 tokens/s band by default. Set config.expectedTokensPerSec to your model's range. An active anomaly also lowers the score until it ends. See Health score.

`hallucinationRisk` is `null`

That's expected: AgentStat can't detect hallucinations. It's null until you send a confidenceScore or the hallucinating status.