# `zfin diagnose`

Trace one symbol's candle data through every tier -- local cache, shared
server, upstream provider -- and say where the chain breaks.

```
Usage: zfin diagnose SYMBOL
```

`diagnose` answers one question: **is the provider behind for this
symbol, or is it us?** It is the counterpart to
[`doctor`](doctor.md), and deliberately its opposite on both axes --
`doctor` checks the whole setup and never touches the network, while
`diagnose` checks a single symbol and queries every tier including the
provider.

It is **read-only**: no cache writes, and the provider query does not
populate the cache. Safe to run while investigating.

## What it reports

Seven lines, in the order the data flows:

| Line        | Says                                                                                                  |
|-------------|-------------------------------------------------------------------------------------------------------|
| `local`     | Newest cached bar, TTL state, which provider sourced it, consecutive failures, any Tiingo backoff      |
| `adj basis` | How current the cached adjusted closes are, against the newest dividend or split that has already gone ex |
| `peers`     | Newest bar held by other cached symbols of the same kind (equity vs mutual fund)                      |
| `tracked`   | Whether a normal run fetches this symbol, or it is only pulled on demand                              |
| `server`    | What `ZFIN_SERVER` offers, whether it is ahead or behind you, and whether it refreshes this symbol     |
| `provider`  | What the upstream provider actually has right now                                                     |
| `verdict`   | Where the chain breaks, and what to do about it                                                       |

## Example

```bash
zfin diagnose SPY
```

```
local      newest 2026-08-19, TTL still in the future, tiingo
adj basis  2026-08-17 - current through the newest corporate action (2026-06-18)
peers      23 other equity cached, newest 2026-08-19
tracked    on demand - a projections benchmark symbol
server     offers 2026-08-19 - same as local, written 2026-08-19, tracked: yes
provider   tiingo newest 2026-08-19 (8 bars in the last 10 days)

verdict    up to date with everything available
```

## Reading the `adj basis` line

This is the least obvious line, so it is worth spelling out. Cached
price history grows by appending, which cannot retroactively correct the
*adjusted* closes of bars already on disk. When a dividend or split goes
ex, those earlier bars need marking down, and until they are, total
returns spanning that ex-date read low by roughly the missed yield. See
[Incremental candle updates](../../explanation/caching.md#incremental-candle-updates).

Three forms:

```
adj basis  2026-08-17 - current through the newest corporate action (2026-06-18)
adj basis  1970-01-01 - STALE, 2026-06-01 went ex behind it; total returns read low until restated
adj basis  2026-08-19 - no dividends or splits cached, nothing to restate
```

`STALE` is not something to act on -- the next refresh re-downloads that
symbol's full history on its own. It explains a total return that looks
slightly low in the meantime.

Two things the date is **not**: it is not when the restatement ran (it is
the newest bar present at the time, which lags when a session's bar has
not posted yet), and it is not an ex-date. `1970-01-01` means "never
restated", which is what a cache predating the feature reads as.

The compared-against date is the newest ex-date that has **already
passed**. A declared-but-not-yet-ex dividend is deliberately ignored:
no provider has applied it either, so waiting on it would refetch
forever.

## Rate limit caveat

The provider query uses its own rate limiter, separate from the budget
the rest of zfin accounts for -- so it is invisible to that budget. On a
free tier close to its cap, `diagnose` can be the request that trips it.
One request per invocation.

## See also

- [`doctor`](doctor.md) -- whole-setup health check, no network.
- [`cache`](cache.md) -- `stale` finds symbols behind their peers; `refresh` forces a local re-fetch.
- [`server`](server.md) -- force a refresh in the shared server's cache instead.
- [Caching and data freshness](../../explanation/caching.md) -- the tiers and TTLs.

---

[CLI command reference](index.md)
