:pins-check

Run a full integrity check on every locally pinned reference. Bee streams one NDJSON record per pin; the cockpit dumps each one to a file as it arrives so you can tail -f it.

:pins-check
:pins         (alias)

What gets checked

Bee's GET /pins/check walks every locally pinned root reference and verifies, per pin:

  • total chunks in the manifest
  • missing — chunks the manifest references but local storage doesn't have
  • invalid — chunks present but failing hash verification

A pin is healthy when missing == 0 && invalid == 0.

Where the file goes

$TMPDIR/bee-tui-pins-check-<profile>-<unix-timestamp>.txt.

Per-profile filename: switching to a different :context mid-check won't conflict with another profile's parallel run. The original check runs to completion against the profile that started it.

The cockpit prints the path in the status line:

pins integrity check running → /tmp/bee-tui-pins-check-prod-1-1715056472.txt
                                (tail to watch progress)

File format

A header followed by one line per pin, ending with a # done. marker:

# bee-tui :pins-check
# profile  prod-1
# endpoint http://10.0.1.5:1633
# started  2026-05-07T08:14:32Z

abcd1234…   total=8192   missing=0     invalid=0    healthy
def56789…   total=1684   missing=12    invalid=0    UNHEALTHY
9876fedc…   total=4096   missing=0     invalid=2    UNHEALTHY
ba98cdef…   total=64     missing=0     invalid=0    healthy
# done. 4 pins checked.

If the check itself errors out (server 500, connection lost), the last line is # error: <message> instead of # done..

The healthy / UNHEALTHY literal at the end of each line is for grep-ability:

grep UNHEALTHY ~/path/to/bundle.txt

…lists every reference that needs attention.

Why this command exists

Locally pinned content is the only reason Bee guarantees chunks remain accessible. If a chunk is missing from a pinned manifest, your data is gone and the network may not have it either (depending on network density). If chunks are invalid, your local storage has been corrupted — disk failure, partial write, etc.

Either case is silent until you check. :pins-check is the audit trail: run it, save the file, and you have a point-in-time integrity snapshot per pinned reference.

How long it takes

/pins/check walks every chunk on disk. For a node with:

  • A handful of small pins (< 10 GB each): seconds.
  • Hundreds of pins or large multi-GB pins: minutes.

The cockpit doesn't block — the check runs in the background, the file appends as Bee streams the response, and you can keep navigating screens. A second :pins-check while one is in flight just kicks off another (Bee does not serialise; the HTTP server handles them in parallel).

What to do with UNHEALTHY pins

For invalid chunks (corruption): your local storage is broken. Best move is to re-download the reference (it's still on the network if other nodes have it) and then re-pin. Long-term, check disk health (smartctl).

For missing chunks: similar — re-fetch from the network or accept the loss. Bee won't auto-heal pins; the operator has to either re-upload or re-pin from a known good source.

If a pin shows missing > 0 and the cockpit's S1 Reserve gate is also failing, your node is in a bad state — drop to S6 Peers + S7 Network to confirm connectivity is OK before re-fetching.

What this command doesn't do

  • Doesn't try to repair anything. Read-only check.
  • Doesn't unpin orphans. Local pins that point to partially-missing references stay pinned; you decide whether to remove them.
  • Doesn't verify network availability. "missing locally" is the only check; if a chunk is missing here but available on the network, Bee will lazily re-fetch it on the next download. The check just reports current local state.

See also