barca status: Fields and JSON
What barca status reports for each node beyond its cache state: the last materialization, the
last changed bytes, the artifact’s shape, run timing and attempts, and what started a run; the
JSON document; and the fine print on targets, limits, an artifact store and disk usage. Reading
status and finding problems is barca status.
Last materialization
Section titled “Last materialization”last_materialization is the most recent execution recorded in the metadata DB, successful or
failed: status, created_at (UTC), elapsed_seconds, run_hash, artifact, format,
size_bytes, rows, and error for a failure. A cache hit is not an execution, so serving from
cache does not change it. It is null when the node never ran.
rows is how many rows a successful tabular result holds, counted by the worker when the step
wrote it (“Row counts” below); null when it was not counted.
Last attempt
Section titled “Last attempt”last_attempt says how the node’s newest attempt went, in one word:
last_attempt |
When |
|---|---|
failed |
its last materialization failed, or any of its keys last failed (partitions.failed is not 0) |
never_run |
no execution is recorded for it (last_materialization is null) |
success |
otherwise |
A partitioned node’s last_materialization is one key, the newest recorded, so its status
can read success while other keys last failed; last_attempt is failed then. It is a fact
of the row, beside cache.state and health and not in place of either: a stale or blocked
node whose last run went well reads success, and a cache hit is not an attempt. A node that
always runs (a task, a sensor) has no cache state to show, so a surface shows this word for it;
the web UI does.
barca status pipeline.py --json | jq -r '.nodes[] | [.name, .cache.state, .last_attempt] | @tsv'last_attempt is experimental with the rest of health.
Row counts
Section titled “Row counts”The worker records the rows of a result when that is cheap to know exactly, and never guesses:
| result | rows |
|---|---|
| a pandas or polars DataFrame, a pyarrow Table, in any format (parquet, CSV, pickle) | its length |
| a polars LazyFrame or a DuckDB relation written to parquet, and each key of a batched call | the row count in the written file’s footer (pyarrow, else duckdb, else polars reads it; only the footer is read) |
| a LazyFrame or relation written to CSV, anything that is not a frame (json, pickle of other values), a failed attempt | null |
Results recorded by an older barca, and results a server’s ledger received from a client, have
null. The count is in last_materialization.rows here, in each step of barca history RUN_ID --json (steps[].rows), in barca stats --json (recent_runs[].rows; for a partitioned
node the rows of the run’s successful keys added up, null unless every one was counted, and
recent_runs[].empty_keys), in barca sql (materializations.rows, nodes.last_rows,
nodes.partitions_empty), and in the server’s routes (Server Mode: a Shared Ledger and –server: Data health).
What the counts say about a node’s data, and how many assets have one at all, is in “Data
signals and coverage” below.
A partitioned node’s partitions.empty counts its keys whose latest successful result wrote no
rows (absent when none did).
For a partitioned node it is one key’s row from the latest run, the first key in sort order
(partition names it), so two identical runs report the same key whatever order the keys
finished in.
Health
Section titled “Health”Every node has a health: one word that says whether something needs doing about it, beside
its cache state and never in place of it. barca status --json, the server’s GET /nodes and
GET /state and barca.nodes in barca sql carry the same word, computed once in barca, and
the web UI shows it. The words, most severe first:
health |
Printed as | Meaning |
|---|---|---|
failing |
failing | its own last attempt failed |
blocked |
blocked | something upstream keeps it from being brought up to date |
suspect |
suspect data | its last run succeeded but its recorded row counts look wrong |
behind |
behind | out of date against its inputs, partly computed, out of sync, or late |
undecided |
undecided | barca cannot decide yet (a cutoff or sensor upstream has not reported) |
never_run |
never run | nothing recorded |
ok |
ok | fresh, or a task or sensor whose last run succeeded |
health_reason names the rule that decided it. The first that applies wins:
health_reason |
health |
When |
|---|---|---|
last_attempt_failed |
failing |
last_materialization.status is failed |
keys_failed |
failing |
partitions.failed is above 0 and the last materialization did not fail |
upstream_failing |
blocked |
a node upstream is failing: an input, or an input of an input that is itself neither failing, cached nor always_runs. A pinned asset (barca pin and unpin) is never blocked and a failure does not pass it |
cache_blocked |
blocked |
cache.state is blocked, or cache.reason is upstream_failed |
empty |
suspect |
it has an empty signal |
rows_changed |
suspect |
it has a rows_changed signal |
behind_input |
behind |
it has a behind_input signal |
schedule_late |
behind |
its schedule missed a slot more than a minute ago (half the interval for a schedule more frequent than every two minutes) and is not paused |
stale, partial, unsynced |
behind |
cache.state is that state |
checked_up_to_date |
ok |
cache.state is unknown, and the newest tick that checked the node found it up to date or rebuilt it, with nothing seen to have changed since (“Last check” below) |
unknown |
undecided |
cache.state is unknown |
never_run |
never_run |
cache.state is never_run |
no_successful_run |
never_run |
a task, sensor or always asset with no recorded run |
on_demand |
ok |
an explicitly Manual task has no run due before its first request |
last_run_succeeded |
ok |
a task, sensor or always asset whose last run did not fail |
cached |
ok |
cache.state is cached |
A partitioned node has one health. A run working on a node does not change it. A node below
a failure is blocked even when its own state is unknown (it waits on a cutoff): the walk
passes through such nodes. barca status scoped to targets reads the targets’ upstream cones,
so a failure above them is seen.
The table prints the words of the nodes it lists under the cache counts, most severe first:
Health: 1 failing, 1 blocked, 2 ok. The line counts every node in scope before filtering or pagination.
barca status --json | jq -r '.nodes[] | select(.health != "ok") | [.health, .health_reason, .id] | @tsv'barca sql "select health, count(*) from barca.nodes group by all order by 2 desc"Health says nothing of whether a behind or never_run node is a problem: its cause does
(“Cause” below), and its root names what explains it (“Root”).
Health is experimental (CLI Contract).
Every node that is not fresh has a cause: one word for why. A node is fresh when its
health is ok or suspect (suspect is about data, not freshness), and then cause is
null. The first row that applies decides:
| # | When | cause |
Printed as |
|---|---|---|---|
| 1 | it is failing; or blocked by a failing node upstream; or its refresh path’s schedule is held after max_failures failed ticks |
failing |
failing |
| 2 | its health is undecided |
undecided |
undecided |
| 3 | a running run computes it | catching_up |
catching up |
| 4 | finished ticks had it as a target and did not leave it fresh (refresh_path.missed_ticks is 1 or more) |
overdue |
overdue |
| 5 | a run that computes it waits for a run slot; or a tick of its refresh path will come and that schedule’s ticks wait: its newest tick is waiting now, or its typical wait exceeds its interval (schedule.queue_bound) |
queued |
queued |
| 6 | no tick will reach it: it has no refresh path, or its path’s schedule is paused until resumed or fired by no scheduler | no_refresh_path |
no refresh path |
| 7 | otherwise: the next tick of its refresh path will compute it | catching_up |
catching up |
catching_up and queued are progress. overdue, no_refresh_path and failing are what
to look at. A cause is never a guess: where barca cannot tell, the word is undecided or
no_refresh_path.
Whether a scheduler is firing. A read-only observer uses the writer’s schedule IDs,
cron timezone, tick decisions and heartbeat. Each served schedule has a next tick and
its nodes use the same estimate rules as on the writer. A graceful stop takes effect as
soon as the observer reads it. If the writer disappears, its heartbeat expires after
45 seconds. An older database with no heartbeat uses each schedule’s decisions and grace.
Affected paths share one scheduler_off root and the action barca serve.
The table of barca status sums the causes of every node in scope under the health words:
Gap: 14 overdue · 152 no refresh path · 180 catching up (nodes); about 180 fresh within 5m, 166 with no estimate (or Gap: every node is fresh). barca.nodes has cause.
barca status --json | jq -r '.nodes[] | select(.cause) | [.cause, .health, .id] | @tsv'barca sql "select cause, count(*) from barca.nodes where cause is not null group by all order by 2 desc"Every node with a cause has a root: the upstream fact that explains it, as {"id": "code:pipeline.py:orders", "kind": "code", "node": "pipeline.py:orders"}. The id is
<kind>:<node id> (or scheduler_off for the scheduler); nodes with the same root.id are held by the same thing, so a few roots
usually explain hundreds of nodes (barca status --rollup lists them, “The rollup” below).
kind |
Printed as | node |
Explains |
|---|---|---|---|
sensor_value |
sensor value | the sensor whose observation is newer than what a node below it read | catching up, overdue, undecided, queued |
code |
code change | the node whose code changed (its function, a decorator, a helper) | same |
env |
environment change | the node whose declared environment variable changed | same |
input |
input change | the fresh node whose result is newer than what a node below it read; or a node out of date with nothing above it or on it that says why | same |
never_run |
never run | the topmost never-run node of the chain (a partitioned node with keys that never ran) | same |
undecided |
undecided | the topmost node barca cannot decide, with nothing above it that explains it | undecided |
no_schedule |
no schedule | the topmost not-fresh node no tick reaches: where a schedule would have to be added, or a Manual or pinned node |
no refresh path |
schedule_paused |
paused | the scheduled node of a paused schedule; or a paused node (barca pause) |
no refresh path |
scheduler_off |
scheduler off | one project-wide root for paths whose schedule has stopped; its id is scheduler_off and its node is empty |
no refresh path |
failure |
failure | the failing node: the node itself, or the nearest one upstream that blocks it; or the scheduled node of a schedule held after max_failures failed ticks |
failing |
queue |
run queue | the scheduled node whose ticks wait for a run slot | queued |
How a root is found:
- Failing: itself, or the failing node that blocks it (the nearest upstream; with two failing inputs, the first by node id).
- Queued by a schedule’s wait: that schedule (
queue). A node queued only because a run someone asked for is waiting keeps the change as its root. - No refresh path: its path’s schedule when it has one (
schedule_pausedorscheduler_off); a paused node is its own root (schedule_paused); otherwise the topmost node of the chain of not-fresh nodes that no tick reaches (no_schedule). A staleManualnode and a pinned asset (barca pin and unpin) are such a top: what is below them and has a path is brought up to date against what they hold. - Undecided where no tick will come: as for no refresh path. Only a run decides the node, so what holds it is the missing tick, not the change above it.
- Everything else (catching up, overdue, undecided with a tick coming): barca walks up
from the node through its inputs that are not fresh and stops at the first node whose own
evidence explains it. That is
cache.changed, what changed in the node’s run hash:code, a decorator or a helper iscode;env NAMEisenv;sensor IDorinput IDnames an input, which is the root when it is fresh (sensor_valuefor a sensor,inputfor an asset) and passes the question up when it is not. A node out of date only because of what is above it takes the root of its first not-fresh input in dependency order. A chain with no such evidence ends at its topmost node:never_run,undecided, orinput.
When a node changed in several ways, its own definition wins: code, then env, then what
it reads. barca.nodes has root_id, root_kind and root_node.
barca status --json | jq -r '.nodes[] | select(.root) | [.root.kind, .root.node, .id] | @tsv'barca sql "select root_kind, root_node, count(*) as held, sum(gap_seconds) as gap from barca.nodes where root_id is not null group by all order by held desc"gap_seconds is the node’s freshness gap: how long it has been out of date (stale_since to
now) plus how long until it is expected fresh (now to expected_fresh_at), in whole seconds
(“Times”). A time that is null counts 0, and a fresh or undecided node has 0. It is read
at the start of the current minute, so it does not change with every second of the clock. A
project’s gap is the sum over its nodes, in node-seconds; a node with no expected_fresh_at
has no forward term, which is why every sum also says how many such nodes it holds
(unbounded).
Cause, root and the gap are experimental with the rest of health.
The rollup
Section titled “The rollup”barca status --rollup --json (and the server’s GET /state/rollup) sums the nodes in scope
into one tree. Nothing else adds health up: the table of barca status --rollup, the web
UI’s health map, bars and failures list all print this document.
{ "as_of": "2026-11-17T16:49:57Z", "entries": [ {"id": "root", "kind": "root", "label": "all", "parent": null, "children": ["group:pipeline.py:ingest", "file:pipeline.py"], "nodes": 6, "assets": 4, "running": 0, "health": {"failing": 1, "blocked": 2, "suspect": 0, "behind": 0, "undecided": 0, "never_run": 0, "ok": 3}, "asset_health": {"failing": 1, "blocked": 2, "suspect": 0, "behind": 0, "undecided": 0, "never_run": 0, "ok": 1}, "data_coverage": {"assets": 4, "measured": 0, "suspect": 0}, "causes": {"catching_up": 0, "queued": 0, "no_refresh_path": 0, "overdue": 0, "failing": 3, "undecided": 0}, "asset_causes": {"catching_up": 0, "queued": 0, "no_refresh_path": 0, "overdue": 0, "failing": 3, "undecided": 0}, "not_fresh": 3, "weight": 21, "weights": {"failing": 18, "overdue": 0, "no_refresh_path": 0, "queued": 0, "undecided": 0, "catching_up": 0, "fresh": 3}, "held_by": [ {"root": "failure:pipeline.py:orders", "nodes": 3, "assets": 3, "causes": {"catching_up": 0, "queued": 0, "no_refresh_path": 0, "overdue": 0, "failing": 3, "undecided": 0}, "gap_seconds": 5400, "unbounded": 3, "weight": 18, "cumulative_nodes": 3} ], "gap_seconds": 5400, "unbounded": 3, "fresh_by": null, "also_in": []} ], "roots": [ {"id": "failure:pipeline.py:orders", "kind": "failure", "node": "pipeline.py:orders", "detail": "ValueError: 12 rows rejected", "error_group": "ValueError: # rows rejected", "nodes": 3, "assets": 3, "causes": {"catching_up": 0, "queued": 0, "no_refresh_path": 0, "overdue": 0, "failing": 3, "undecided": 0}, "gap_seconds": 5400, "unbounded": 3, "weight": 18, "action": {"kind": "fix_failure", "command": "barca get orders", "estimated_seconds": 42}} ], "data_coverage": {"assets": 4, "measured": 0, "suspect": 0}, "files": [ {"file": "pipeline.py", "nodes": 6, "assets": 4, "running": 0, "health": {"failing": 1, "blocked": 2, "suspect": 0, "behind": 0, "undecided": 0, "never_run": 0, "ok": 3}, "asset_health": {"failing": 1, "blocked": 2, "suspect": 0, "behind": 0, "undecided": 0, "never_run": 0, "ok": 1}, "worst": "failing", "causes": {"catching_up": 0, "queued": 0, "no_refresh_path": 0, "overdue": 0, "failing": 3, "undecided": 0}, "fresh": 3, "kinds": {"asset": {"nodes": 4, "fresh": 1, "causes": {"catching_up": 0, "queued": 0, "no_refresh_path": 0, "overdue": 0, "failing": 3, "undecided": 0}}, "task": {"nodes": 1, "fresh": 1, "causes": {"catching_up": 0, "queued": 0, "no_refresh_path": 0, "overdue": 0, "failing": 0, "undecided": 0}}, "sensor": {"nodes": 1, "fresh": 1, "causes": {"catching_up": 0, "queued": 0, "no_refresh_path": 0, "overdue": 0, "failing": 0, "undecided": 0}}}} ], "kinds": {"asset": {"nodes": 4, "fresh": 1, "causes": {"catching_up": 0, "queued": 0, "no_refresh_path": 0, "overdue": 0, "failing": 3, "undecided": 0}}, "task": {"nodes": 1, "fresh": 1, "causes": {"catching_up": 0, "queued": 0, "no_refresh_path": 0, "overdue": 0, "failing": 0, "undecided": 0}}, "sensor": {"nodes": 1, "fresh": 1, "causes": {"catching_up": 0, "queued": 0, "no_refresh_path": 0, "overdue": 0, "failing": 0, "undecided": 0}}}}entries lists the root first, then every entry depth first, a level’s children in the order
of children.
| Key of an entry | Meaning |
|---|---|
id, kind |
root (id root), group (the group’s id, group:<file>:<name>), file (file:<path>: the nodes of that file that are in no group) or node (the node id) |
label |
the group’s or node’s name, the file’s path, all for the root |
parent, children |
the entry it sits under (null for the root) and the entries under it: worst health first, then most assets, then label |
nodes, assets |
nodes underneath (1 for a node), and how many of them are assets: tasks and sensors are nodes, not assets |
running |
nodes underneath a run is working on now; 0 without a server |
health, asset_health |
how many nodes, and how many assets, are in each health |
data_coverage |
the coverage of “Data signals and coverage”, for the assets underneath |
causes, asset_causes |
how many nodes, and how many assets, that are not fresh have each cause (“Cause”); they add up to the nodes (assets) whose health is not ok or suspect |
not_fresh |
nodes underneath that are not fresh: what causes counts, as one number |
weight |
the entry’s distance from fresh, in weighted nodes: every node underneath counts 1, and one that is not fresh counts its cause’s weight instead: 6 for failing, overdue and no_refresh_path (someone has to act), 2 for queued, catching_up and undecided (it will be fresh without anyone acting, or barca cannot say). A fully fresh scope weighs its nodes. The web UI’s health map sizes a segment by it |
weights |
weight by what the nodes are: one number per cause (its nodes times its weight) and fresh (the fresh nodes, 1 each). They add up to weight |
split |
counts of actionable, waiting and hand-run roots (need_someone, catching_up, run_by_hand); node counts and weights for actionable and in-hand roots. Groups sort by actionable weight then in-hand weight. |
stale_since |
oldest recorded stale time underneath |
held_by |
the roots that hold those nodes, each with what it holds underneath this entry: root (an id of roots), nodes, assets, causes, gap_seconds, unbounded, weight (the weight of those nodes), and cumulative_nodes (the nodes held by this root and the ones listed before it). In the order of roots, applied to what is held here; their nodes add up to not_fresh. Empty on a node entry, whose root is on its row |
gap_seconds |
the freshness gap underneath, node-seconds: the sum of the nodes’ gap_seconds (“Root”) |
unbounded |
nodes underneath that are not fresh and have no expected_fresh_at (“Times”): nothing known will leave them fresh, so the gap has no forward term for them |
fresh_by |
the latest expected_fresh_at underneath (RFC 3339, UTC): when the nodes that have an estimate are all expected fresh. null when none has one. It speaks only for those nodes; unbounded counts the rest |
keys |
on a partitioned node only: its keys that failed, are behind (no cached result, and did not fail) and are ok, and cause, why the keys that are behind are not fresh: the node’s own cause, null for a fresh node |
also_in |
the other groups that declare this node or group, by id; empty for one declared in at most one group |
Every node has exactly one parent, so every count of an entry is the sum of its children’s. A
node declared in several groups is counted under the first of them by group id and names the
others in also_in; a group with no node in scope is not listed.
files cuts the same nodes by source file: one object per file in scope, by path, with its
nodes, assets, running, health and asset_health summed over every node of the file,
in whichever group each sits, worst, the most severe health among them, and causes and
fresh: its nodes that are not fresh by cause, and those that are. The tree has a file
entry only for the nodes of a file that are in no group, so a list of files (the web UI’s
sidebar, which marks a file with the first cause it has a node of) reads files.
kinds cuts them by kind: asset, task and sensor, each {"nodes", "fresh", "causes"}:
how many nodes of the kind are in scope, how many of them are fresh (no cause) and how many
have each cause; fresh and the causes add up to nodes. The document carries it for the
whole scope and each entry of files for its file. A list of one kind (the web UI’s Assets,
Tasks and Sensors pages) reads its filter counts there instead of counting rows.
roots is the to-do list: what holds the nodes that are not fresh, and what clears each.
There is one entry per root the nodes carry (“Root”), and every node that is not fresh is
under exactly one, so the roots’ nodes add up to the nodes that are not fresh.
A stopped scheduler ranks first. Among the remaining roots, those whose actions need someone lead. Within each part the list is ranked by weight, the most first: a root that holds 152 nodes nothing will
refresh (6 each) comes before one that holds 180 the next tick computes (2 each). Among roots
of the same weight a failure comes first, then the most nodes, the largest gap_seconds,
and the id.
A root’s numbers are over every node in scope; what it holds under one group or file is that
entry’s held_by, which is the same list cut to the entry, so a group’s to-do list is its own
entry’s. cumulative_nodes against not_fresh says how much the head of a list explains:
barca status --rollup prints “The first 3 hold 338 of them.” under the list’s heading when
there are more than three roots.
| Key of a root | Meaning |
|---|---|
id, kind, node |
the root its nodes carry |
detail |
the fact in a line: a failure’s error (its first line, or the last line of a bare traceback; 3 of 8 keys failed for a node whose keys failed with no error of its own), the code of orders changed, no tick reaches ledger, inbox's schedule is paused, pulse's ticks wait about 2m for a run slot, every 1m: max_runs is 1 |
error_group |
a failure’s error line with its numbers replaced by #, so failures that differ only in their numbers share one; null for every other kind and when no error was recorded |
nodes, assets |
how many nodes it holds, and how many of them are assets |
causes |
those nodes by cause |
gap_seconds |
the sum of their gap_seconds |
unbounded |
how many of them have no expected_fresh_at |
weight |
the weight of the nodes it holds (each counts its cause’s weight, as on an entry): what the list is ranked by |
needs_someone |
whether someone needs to act |
stale_since, fresh_by |
oldest stale time and latest known estimate among held nodes |
action |
kind, command, estimated_seconds and run_once (a one-time command for an unscheduled chain) |
action.kind |
Printed as | For | command |
|---|---|---|---|
wait |
wait | a change the next tick or a run in flight computes; an undecided chain; a tick waiting for a slot on a schedule that is not queue-bound | null |
run |
run | a change whose nodes ticks already missed (overdue): barca get of the held nodes nothing else held reads (barca run when they are all tasks), which computes everything above them. A pinned root: barca unpin <node> |
the command |
run_by_hand |
run by hand | a Manual node or unscheduled task, when its result is wanted | the command |
add_schedule |
add a schedule | a chain no tick reaches: give its top, or a node above it, freshness=Schedule(...) |
null |
resume_schedule |
resume | a paused node: barca resume <node> --server. A paused schedule: barca resume --schedule <node> --server (Scheduling With Cron, “Pausing one schedule”) |
the command |
start_server |
start a server | a schedule no scheduler fires | barca serve |
fix_failure |
fix the failure | a failing node: the command tries it again once the error is fixed (barca get <node>, barca run <node> for a task) |
the command |
raise_max_runs |
raise max_runs | a queue-bound schedule: give the server more run slots (barca serve --max-runs N, [server] max_runs) or space the schedules (Scheduling With Cron, “When ticks wait for a run slot”) |
null |
A command names a node by its name, or by its id when two nodes in scope share the name, and
ends in --server when a server answered (GET /state/rollup, barca status --rollup --server): the run belongs in that server’s queue. estimated_seconds is the typical compute
time of the nodes the root holds: the sum of their typical step durations (the median of a
node’s recent successful runs, once per key without a result for a partitioned node; the
project’s median for a node with none), in whole seconds, and null when none of them has a
sample. It is work, not wall-clock time: steps of one run share the worker pool.
data_coverage at the top is the root entry’s.
barca status --rollup prints the list under the tree:
What holds the 4 nodes that are not fresh, and what clears it:1 needs you · 1 is catching up1. no schedule: source holds 1 node (1 asset): 1 no refresh path; 1 with no estimate; weight 6 why: no tick reaches source do: add a schedule: freshness=Schedule(...) on it or on a node above it run once: barca get source2. sensor value: changes holds 3 nodes (3 assets): 3 catching up; 15m of gap across nodes (node-time); weight 6 why: changes observed a new value do: waitbarca status --rollup --json | jq -r '.entries[] | select(.kind == "group") | [.label, .nodes, .assets, .health.failing] | @tsv'barca status --rollup --json | jq -r '.roots[] | [.nodes, .kind, .node, .action.kind, .action.command // "-"] | @tsv'barca status --rollup --json | jq '.entries[0] | {causes, gap_seconds, unbounded, fresh_by}'barca status --rollup --json | jq -r '.entries[] | select(.kind == "group") | .label as $g | .held_by[] | [$g, .nodes, .root] | @tsv'The rollup is experimental (CLI Contract). A scope given as targets is their upstream
cones, so a rollup of one group also counts what that group reads from outside it. Known
limits: an
input root is named from what the node’s run hash recorded, so a result recorded before
0.29.0 (no components) roots at the node itself; and the command of a run action lists
every held node nothing else held reads, which for a wide fan-out is a long line.
Last check
Section titled “Last check”last_check is what the newest finished tick that had the node as a target did with it
(Scheduling With Cron): {"at": "2026-11-17T15:00:05Z", "outcome": "up_to_date", "schedule": "pipeline.py:inbox"}, or null when no retained tick did. at is when that tick’s run ended
(RFC 3339, UTC), schedule the scheduled node whose tick it was, and outcome one of:
outcome |
The tick’s run |
|---|---|
rebuilt |
executed its step, which succeeded. For a sensor that means it was polled, whatever it returned; for a task, that it fired |
up_to_date |
found a cached result for its code and inputs: a cache hit |
failed |
executed its step, which failed |
not_reached |
ended before it decided the node: a failure upstream, a cancellation, a run that never started |
It is a record, shown whatever its age. Ticks are recorded by a scheduling barca serve
(schedule_ticks in the metadata database); barca status on that machine and a
--read-only server read the same record. Each schedule keeps the outcomes of its newest 20
fired ticks, and with several schedules reaching a node the newest tick wins.
When a check decides health. barca status and GET /state predict what a barca get
would do, without running anything. Where the answer depends on what only a run produces, the
node’s state is unknown (barca status: Cache state): below an @asset(cutoff=True)
that would run, the bytes it will write. A tick does run. It also reads a node paused with
barca pause as it is, where a get (and so the prediction) recomputes it, so below a
paused node it can find a node up to date every five minutes while its state stays unknown.
(A Manual or pinned node is read as it is by every run, and by the prediction.) Such a
node is ok with health_reason: "checked_up_to_date" when all of this holds:
- its state is
unknownand no earlier rule applies (it is not failing, blocked, suspect, or the scheduled node of a late schedule); - its last check’s
outcomeisup_to_dateorrebuilt: a newerfailedornot_reachedcheck is the last check, and decides nothing; - the check has not expired. It stands for one interval of its schedule after its run ended, plus the time that tick took from its slot to its end, plus the grace a late schedule gets (a minute; half the interval for a schedule more frequent than every two minutes): by then the next tick’s check is due. A tick found up to date at 15:00:05 by a five-minute schedule stands until 15:06:10. The check of a schedule that is no longer in the project never stands;
- the node’s definition (its code, counted decorator arguments and helpers) is the one its newest successful result recorded: an edit since is seen;
- no node above it has a materialization recorded after that tick’s run ended, other than by a tick’s run still in flight (whose own check is on its way).
Otherwise the node keeps the health its state gives (undecided). A node whose check stands
gets no behind_input signal: the tick read its inputs’ newest results and found it up to
date. Not seen until the next tick or the expiry: an edit to a node above it (which shows on
that node), and a new value of an environment variable it declares.
The table adds the check to the WHY of a node whose state is unknown: cutoff_pending; checked 3m ago, up to date. barca.nodes has it as last_check_at and last_check_outcome.
barca status --json | jq -r '.nodes[] | select(.last_check) | [.id, .last_check.outcome, .last_check.at] | @tsv'barca sql "select name, health, last_check_outcome, last_check_at from barca.nodes where health_reason = 'checked_up_to_date'"last_check and checked_up_to_date are experimental with the rest of health.
Refresh path
Section titled “Refresh path”refresh_path is the schedule whose tick brings the node up to date, or null when no tick
ever will:
{"schedule": "pipeline.py:inbox", "next_tick": "2026-11-17T15:00:00Z", "paused": false, "live": true, "missed_ticks": 0}A node has a path through a schedule exactly when that schedule’s tick has the node as a
target (Scheduling With Cron, “What a tick does”): the scheduled node itself, the Always
nodes below it, and the Always nodes below every sensor without a schedule of its own that
the tick’s run polls. It is the scheduler’s own list, read back per node. So these have no
path:
- a
Manualasset or task: a tick reads it as it is. TheAlwaysnodes below it still have theirs; - an
Alwaysnode with no scheduled node above it and no polled sensor above it; - a sensor a tick only polls as an input (it is polled, not targeted);
- a paused node (
barca pause), which a tick skips, and a pinned asset (barca pin), which a tick reads as its pinned result. What is below either keeps its own path.
| Field | Meaning |
|---|---|
schedule |
the scheduled node’s id. With several schedules reaching the node, the one that fires earliest next; a schedule with no next tick comes last, and ties go to the lower id |
next_tick |
that schedule’s next slot (RFC 3339, UTC); the first slot after a timed pause ends; null for a pause until resumed and when live is false |
paused |
the schedule is paused (barca pause --schedule NODE, POST /schedule/{id}/pause). A paused schedule is still the path |
live |
a running scheduler fires the schedule. false when no scheduler is observed firing this schedule and for a schedule held after max_failures failed ticks (schedule.failing) |
missed_ticks |
how many finished ticks of the path’s schedules had the node as a target and did not leave it fresh |
missed_ticks reads the tick record (last_check above): it counts the ticks whose outcome
for the node was failed or not_reached, from the newest back to the last tick that found
the node up to date or rebuilt it, and only those that ended after the node’s newest
successful result (a run nobody scheduled made the earlier ones good). It is 0 for a fresh
node (health ok or suspect). Each schedule keeps the targets of its newest 20 fired
ticks, so the count stops there; a tick that was skipped or never fired is not a miss, and a
database with no tick record counts none.
The table adds the path to the WHY of a node that is not fresh: upstream_stale; next tick 15:05 UTC by inbox (the day is named when it is not today), inbox is paused, inbox is not firing, with , missed 2 ticks when ticks missed it; and no refresh path where nothing
will refresh it, when a node shown is scheduled or has a path (a project with no schedule
has none anywhere). A scheduled node’s own schedule is in its SCHEDULE cell. barca.nodes
has refresh_schedule, next_tick and missed_ticks, all null for a node with no path.
barca status --json | jq -r '.nodes[] | select(.health != "ok" and .refresh_path == null) | .id'barca sql "select name, health, refresh_schedule, next_tick, missed_ticks from barca.nodes where health <> 'ok' order by missed_ticks desc"refresh_path is experimental with the rest of health.
Three times say how far a node that is not fresh is from fresh. Each is RFC 3339 UTC or
null, and none is a guess: a time barca cannot tell is null.
| Field | Meaning | null when |
|---|---|---|
stale_since |
since when the node has been out of date: the earliest recorded time from which it has been continuously not fresh | the node is fresh (health ok or suspect) or undecided; or no record holds the time |
expected_fresh_at |
when the node is expected to be fresh: an estimate, rounded up to 5 seconds | the node is fresh; or no run is known to leave it fresh (below) |
recheck_at |
when a tick next looks at the node: the next_tick of its refresh path |
it has no refresh path, or the path has no next tick |
“Fresh” and “rechecked” are different promises. expected_fresh_at is given only where a
run will compute the node and leave it fresh. recheck_at only says a tick will look: the
node may be found up to date, be rebuilt, or be left as it is. A node with recheck_at and
no expected_fresh_at is rechecked then, not fresh then, and every surface words it so
(fresh ~15:05 UTC against rechecked 15:00 UTC).
A node with no estimate says why. no_estimate is one word for a node that is not fresh
and has no expected_fresh_at, null for a fresh node and one that has an estimate. The
first that applies:
no_estimate |
Shown as “no estimate: …” | When |
|---|---|---|
failing |
until the failure is fixed | its cause is failing |
paused |
paused | its root is a paused schedule or a paused node |
scheduler_off |
no scheduler is firing its schedule | its root is scheduler_off |
no_path |
no refresh path | its root is no_schedule, or its cause no_refresh_path |
undecided |
undecided until a run reports | its cause is undecided |
missed |
ticks missed it | its cause is overdue |
queue_stopped |
the run queue is not starting runs | a tick or a run will reach it, and the run queue is paused or draining |
no_scheduler_here |
no scheduler runs here | a tick will reach it, and the records provide no next tick to estimate from |
not_promised |
a result above it may come out unchanged | a tick will look at it and may find it up to date or leave it as it is (recheck_at only) |
stale_since is, for the node itself:
| The node is | stale_since |
|---|---|
| failing | its first failed attempt since its last clean run |
stale because an input changed (inputs_changed: a sensor’s new observation, an asset’s new result) |
when the earliest such input result newer than the node’s own was written |
behind an input (behind_input) |
when that input’s newer result was written |
| the scheduled node of a late schedule | the first slot no tick fired for (schedule.late_since) |
stale because its code changed (code_changed), or never run |
when its source file was last modified, if that is after the node’s newest result |
stale only because an environment variable changed (env_changed), partial, unsynced |
null: nothing records when |
and for a node that is out of date because of what is above it (upstream_stale, blocked),
the earliest of its own time and the times of the nodes above it that are not fresh: it has
been out of date as long as they have. The file’s modification time stands for a code change
because nothing records when barca first saw a definition. It is never before the edit, but
an unrelated later edit to the same file moves it forward, so the node has been out of date
for at least that long, possibly longer; a helper in another file that changed is not seen,
and the time is null.
expected_fresh_at is the start of the run that will compute the node plus the node’s place
in that run:
- The run is the first that applies: a running run that computes the node, counted from
its latest progress (its start, or the last step it finished); a run waiting in the run
queue that computes it, from its
estimated_start_at(GET /queue); else the next tick of the node’s refresh path: the slot, plus the schedule’s typical queue wait (schedule.typical_queue_wait_seconds), or when the run queue clears if that is later. - The node’s place is the typical duration of each step before it and its own: the median of a node’s recent successful runs (the project’s median for a node with none; once per key without a result for a partitioned node). A step starts when its inputs are done and a worker is free: steps are taken in the order they become ready, and each also waits for the work taken before it divided over the worker pool. With enough workers that is the longest chain above the node; with one it is the sum. A sensor’s poll and a task that runs on every tick count as work.
- No estimate (
null) for a node that is failing or blocked (the failure is what holds it),undecidedor in cache stateunknown(the run may find it up to date), below a node that is not fresh and that the run does not compute (a staleManual, paused or pinned node: the tick reads it as it is), missed by a tick already (refresh_path.missed_ticks, unless a run is computing it now), without a refresh path, or while the run queue is paused.barca statuson a machine with no server estimates nothing: no scheduler fires here.
What it does not model: a run’s startup (workers importing the project), steps heavier than
one unit of capacity, other runs sharing the server’s capacity, and retries. On a server with
one run slot, two schedules ticking every 10 seconds and steps of 0.4 to 3 seconds, the
estimates were 2 to 4 seconds later than the time each node became fresh, most of it the
rounding up; the test that measures it holds them to 8 seconds
(python/tests/test_estimates.py).
The table adds the estimate to the WHY of a node that is not fresh: fresh ~15:05 UTC
(to the minute, rounded up), or overdue 16h for a node ticks have missed (how long it has
been out of date). A node with only a recheck already names its next tick there. A rollup
entry carries fresh_by, the latest expected_fresh_at underneath, and unbounded, how
many nodes underneath are not fresh and have none. barca.nodes has stale_since,
expected_fresh_at and recheck_at.
barca status --server --json | jq -r '.nodes[] | select(.expected_fresh_at) | [.name, .stale_since, .expected_fresh_at] | @tsv'barca sql "select name, health, stale_since, recheck_at from barca.nodes where health <> 'ok' and expected_fresh_at is null"The times are experimental with the rest of health.
Typical run time
Section titled “Typical run time”typical_run_seconds is how long one run of the node typically takes, in seconds: the median
of its recent successful executions (at most 20; the middle value, or the mean of the two
middle values of an even count). Durations are recorded per key, whichever call computed the
key, so for a partitioned node the figure is that median times its number of keys
(partitions.total): a run over the whole node. It is rounded to a millisecond, and null
when the node has no successful execution on record.
It is an estimate of a run that computes every key. The next run computes only the keys that
need it, which expected_fresh_at accounts for and this does not. For a node whose keys are
computed in batched calls the per-key median is small and the product is the time of the
calls; for keys that run side by side on several workers the wall time is shorter than the
figure.
barca status pipeline.py --json | jq -r '.nodes[] | select(.typical_run_seconds) | [.name, .typical_run_seconds] | @tsv'typical_run_seconds is experimental with the rest of health.
Data signals and coverage
Section titled “Data signals and coverage”signals lists what a node’s recorded results say about its data, from facts the metadata DB
holds (row counts workers recorded, when each result was written), never by reading an
artifact. Only assets have signals, in this order:
kind |
When | Fields |
|---|---|---|
empty |
its latest successful result wrote no rows: for a partitioned node, some keys’ latest successful results | empty_keys of keys (the keys whose latest result recorded a count; 1 of 1 without keys), previous_empty_keys: how many were empty before its newest run, null when no key had a counted result before it |
rows_changed |
a latest successful result’s row count differs from the one before it, same node and key, by more than half of it (any rows after an empty result count) | rows and previous_rows of key (null without keys), the key that moved the most relative to before; changed_keys: how many moved |
behind_input |
its cache state is unknown (nothing else says it is behind, typically a collect() fan-in below a pending cutoff), no tick’s check of it stands (“Last check” above) and its latest successful result is older than the newest successful result of an asset it reads, from another run |
input (the input with the newest result), input_success_at, last_success_at (UTC YYYY-MM-DD HH:MM:SS) |
A signal stays until the next successful result of the node (or key) replaces the one it is
about; there is no acknowledgement yet. A stale, partial or blocked node gets no
behind_input: its state already says it will run.
An empty signals does not mean the data is fine. A signal can only be raised for a result
whose rows were counted (“Row counts” above), so each asset says whether it was: measured is
true when its latest successful result has a recorded row count (for a partitioned asset,
any key’s), false when it has none, and null for a task or sensor. An asset with
measured: false is not measured, never ok for data.
data_coverage, beside summary, counts this for every node in scope (a filter does not
change it): assets, how many of them are measured, and how many of those are suspect
(an empty or rows_changed signal). The table prints it as its last line but one, Data: 7 of 556 assets measured, with , 2 suspect when some are, so “no suspect data” is never said
without what it is out of.
barca status --json | jq '.data_coverage'barca status --json | jq -r '.nodes[] | select(.signals != []) | [.id, (.signals | map(.kind) | join(","))] | @tsv'barca sql "select count(*) filter (where measured) as measured, count(*) as assets from barca.nodes where kind = 'asset'"Last changed bytes
Section titled “Last changed bytes”last_bytes_change is the most recent recompute of the node that produced different bytes for
the same code and inputs (the same run hash): {node_id, run_hash, content_hash, created_at},
with the exact node id (a partition key included). It is absent when that never happened. The
table prints one line per such node under the rows:
total: different bytes for the same code and inputs at 2026-10-02 11:56:43 UTC (pipeline.py:total).
It means the function is not deterministic (The Cache).
Artifact shape
Section titled “Artifact shape”shape describes the artifact of last_materialization when that run succeeded (null
otherwise). It is read from the file alone by a small Python helper; your modules are never
imported.
| format | shape |
|---|---|
| parquet | type: "table", rows, columns: [{name, type}] (arrow types) from the file footer |
| json list | type: "list", rows; for a list of objects also columns with the JSON types seen (str | null) |
| json object | type: "dict", keys (first 100; key_count when there are more) |
| other json | type (int, str, …) |
| pickle | type only, e.g. myproject.Model, read from the pickle opcodes without unpickling |
--sample N adds sample: the first N rows (parquet, json list), the first N entries (json
object), or the value (other json). It is off by default to keep output small. Pickles are never
sampled: loading one would import and run code.
When the shape cannot be read, shape has a note instead of rows/columns: parquet without
pyarrow installed (pip install 'barca[parquet]'), a file that no longer exists, or a remote
artifact that is too large or cannot be reached (below).
Remote artifacts
Section titled “Remote artifacts”With remote storage (Remote Storage) the shape is read from the bucket, through the same
filesystem, credentials and [remote.storage_options.*] the steps use. There is no flag for it:
barca status total --json --sample 2 # rows, columns and 2 sample rows, read from the bucket- parquet:
rowsandcolumnscome from the file footer by ranged requests; the object is not downloaded.--sample Nalso reads the first row group, not the whole file. Measured on a 160 MB file of 20 row groups in S3-compatible storage: 64 KB read for the shape, 8 to 9 MB with--sample 5. - json and pickle have to be downloaded to be described, so only objects up to 16 MB are. A
larger one has
"note": "remote json artifact too large to inspect: 25.1 MB (limit 16 MB)".barca sqlcan still query a large json result.
Each node with a result costs one or two requests, and up to 8 artifacts are read at a time.
barca status with no target reads every node; name a target to read only its upstream cone.
A store that cannot be read never fails the command. A missing driver
(pip install 'barca[s3]'), rejected credentials or a network error is the note of each
shape, the rest of the status is complete, and the exit code is 0. After the first such failure
the artifacts not yet read report it without another attempt, so an unreachable bucket costs one
wait for the driver’s retries (about 10 seconds for an S3 endpoint that refuses connections),
not one per node.
Partitioned assets
Section titled “Partitioned assets”A partitioned asset is one node with a partitions summary: total, cached, missing and up
to 20 missing_keys, and empty when some keys’ latest successful result wrote no rows (a
recorded count of 0; keys no longer in the key set count while their result is recorded).
The missing keys are counted three ways, which add up to missing: failed (their last
attempt failed; absent when none did), blocked (they wait on the same keys of an input,
which failed, named by id in blocked_on; both absent when none does) and behind (stale or
never run: a run computes them). Its state is cached when every key is, partial when some are, and
stale/never_run when none are. last_materialization is one key of the latest run (the first in
sort order), named in its partition field (for example k=a), and shape describes that one key’s artifact.
The keys themselves, each with its state, latest attempt, rows and error, are
barca status NODE --keys, which takes filters, an order and a page; what is wrong and where,
with the grid’s rows, is --overview; every key’s state at once is --grid, and one key
along its chain is --key KEY (Partitions: Listing keys).
{ "target": "total", "targets": ["total"], "nodes": [ { "id": "pipeline.py:orders", "name": "orders", "kind": "asset", "inputs": [], "partitioned": false, "cache": {"state": "cached", "reason": "materialized", "detail": "...", "run_hash": "6db9...", "artifact": ".barca/artifacts/pipeline.py--orders/6db9....parquet"}, "health": "ok", "health_reason": "cached", "signals": [], "measured": true, "cause": null, "root": null, "gap_seconds": 0, "last_check": null, "refresh_path": null, "stale_since": null, "expected_fresh_at": null, "recheck_at": null, "no_estimate": null, "last_attempt": "success", "typical_run_seconds": 0.54, "last_materialization": {"status": "success", "created_at": "2026-10-02 11:56:43", "elapsed_seconds": 0.54, "run_hash": "6db9...", "artifact": ".barca/artifacts/pipeline.py--orders/6db9....parquet", "format": "parquet", "size_bytes": 2182, "rows": 3}, "shape": {"type": "table", "rows": 3, "columns": [{"name": "id", "type": "int64"}, {"name": "amount", "type": "double"}]} } ], "summary": {"cached": 2, "unsynced": 0, "stale": 0, "never_run": 0, "partial": 0, "blocked": 0, "unknown": 0, "always_runs": 0}, "data_coverage": {"assets": 2, "measured": 1, "suspect": 0}, "as_of": "2026-10-02T11:57:10Z", "rollup": {"id": "root", "kind": "root", "label": "all", "parent": null, "children": [], "nodes": 2, "assets": 2, "running": 0, "health": {"ok": 2, "...": 0}, "asset_health": {"ok": 2, "...": 0}, "data_coverage": {"assets": 2, "measured": 1, "suspect": 0}, "causes": {"catching_up": 0, "...": 0}, "asset_causes": {"catching_up": 0, "...": 0}, "gap_seconds": 0, "unbounded": 0, "fresh_by": null, "also_in": []}}as_of is the instant the nodes were classified at (every derived time and gap_seconds are
as of it), and rollup the scope summed: the root entry of barca status --rollup --json
(“The rollup”), for every node in scope whatever --state, --problems or --limit cut from
nodes. Its children are empty here; the tree and the roots are the rollup’s own document.
A scheduled node adds "schedule": {"cron": "0 6 * * *", "next_fire": "2026-10-23T06:00:00Z", "last_fired": null, "last_status": null, "last_run_id": null, "late": false, "late_since": null, "failures": 0, "max_failures": 5, "failing": false, "paused": false, "paused_until": null, "skip_reason": null, "live": false, "typical_queue_wait_seconds": 0, "typical_run_seconds": null, "queue_bound": false} (the last
three: how long its ticks’ runs typically wait for a run slot and take, in whole seconds, and
whether the wait exceeds its interval; Scheduling With Cron), and --state or
--problems add "filter" beside summary. health, health_reason, cause, root, gap_seconds, signals,
measured, last_check, refresh_path, the three times and data_coverage are in “Health”,
“Cause”, “Root”, “Last check”, “Refresh path”, “Times” and “Data signals and coverage” above; here total is a dict, which has no row count, so one of the two assets
is measured.
Keys inside a sample row are printed in alphabetical order; columns keeps the file’s column
order. --env <name> reads another environment’s state (The Cache).
An explicit @asset(name="orders_clean") uses orders_clean in status and as its SQL
view name, matching list, get and stats. Inspection reads the existing artifact
without importing or rerunning its producer.
Run timing and attempts
Section titled “Run timing and attempts”get --json and run --json add elapsed_seconds and attempts to executed steps,
including failed steps. Cached steps and dry runs omit them. Elapsed time sums active
worker time across attempts: module import, input loading, the call and artifact
serialization; retry backoff is excluded. After a worker disconnect, elapsed time falls
back to the coordinator’s observed in-flight time. For a partitioned step, elapsed time
sums its executed keys (and can exceed run wall time); attempts is the maximum for any
one key, not the number of keys.
barca get total pipeline.py --json --fields id,status,elapsed_seconds,attempts,import_secondsbarca history --json --fields run_id,status,attemptsbarca stats total pipeline.py --jsonUnder --agent (and in every run barca serve starts), a worker prints
[barca] importing <module> on stderr before it imports a module; without --agent it prints
nothing of its own, and the import time is in the run JSON. Imports longer than one second add import_seconds to the step report, summed across
attempts and executed keys. This time is included in elapsed_seconds; it is not an
extra charge. A reused module adds no import time. Framework import diagnostics remain
visible under --json; task prints remain accessible through barca logs.
--agent completion and final failure lines append attempts=N when N exceeds one.
Completion lines retain their existing final-attempt duration. history --json adds
attempts, the total attempts in recorded materialization rows (zero for an all-cached
run; upload-failure rows from earlier versions retain their transfer-attempt counts). stats shows
attempts per recorded materialization and its stored final-attempt duration. For a partitioned
node (barca stats scored) an execution is a run: total_runs counts runs, elapsed_seconds and
cpu_seconds sum its keys, and each recent_runs entry adds keys, failed_keys and
empty_keys (keys that wrote no rows).
Timeout errors name the step id, including its partition key.
Older read-only snapshots without attempt metadata report a null history attempt total.
What started a run
Section titled “What started a run”barca history --json rows carry triggered_by: manual for a command typed on a machine
(barca get, barca run), api for a run started over HTTP on barca serve, schedule for a
cron tick, and client for a run a laptop posted to a server’s ledger. A scheduled run also
carries the tick it was started for in scheduled_at (RFC 3339, UTC) and the scheduled node in
schedule_id; both are null otherwise. Runs recorded before barca recorded this have
triggered_by: null.
barca history --json --fields run_id,triggered_by,scheduled_at,schedule_idDetails
Section titled “Details”Status executes no pipeline step and records no new run, and it does not create .barca/.
Source parsing is static, but partitions(<expression>) may evaluate Python and import its
module while resolving keys. Times in the table (LAST RUN, like STARTED in barca history
and CREATED in barca stats) are UTC and say so; the JSON has the same UTC values. Like every inspection command, the result goes to stdout (a table in a terminal, JSON
when piped; --json / --pretty override) and errors to stderr; an unknown target is a usage
error (exit 2) that ends with Run `barca list <files>` to see available assets and tasks.,
the same remediation as get and run. A target is one name or several, comma-separated with no
spaces (a,b), parsed exactly as get and run parse them; the JSON names them in targets
(and the single one in target).
With an artifact store (Remote Storage), status also asks the store about every cached
unpartitioned node, with one python -m barca._state stat for all of them, and reports a node
whose copies do not agree as unsynced (barca status: Cache state). Nothing is downloaded or uploaded.
Status reads the metadata DB as it is at that moment, and a run records each step as it
finishes. So while a barca get is running, status in another terminal already shows the steps
it has finished as cached (a partitioned asset as partial, with counts); see barca docs layout, “While a run is going, and after one is killed”.
Like list, status returns every node in JSON unless --limit N is explicit. The human
table shows at most 100 nodes unless you pass --limit N or --all. The
summary still counts every node, and the JSON adds total and truncated (with a hint when
truncated). Each node also lists env, the environment variables it declares with env=[...]
(Assets, Sensors and Inputs), and, when its code reads variables it does not declare, undeclared_env
(experimental; The Cache: Environment variables). --fields keeps only the named keys
on each node.
Disk usage and inspection cost
Section titled “Disk usage and inspection cost”The experimental disk_usage summary reports project-wide storage across all environments,
even when node selection or filters narrow the graph: budget_bytes, backup_bytes,
physical size_bytes and limit_bytes. Recognized local metadata backups are outside the
cache budget and included in the physical total. Human output shows the same distinction.
Budgeted bytes use the last maintained GC measurement; status does not walk artifacts or
refresh that measurement. Backup directories are checked directly with a bounded survey
(at most 4096 directory entries across environments and backup files). Unmeasured counts,
including an incomplete backup survey, are null and displayed as unmeasured. Use barca doctor or barca gc --dry-run for a full measurement. Server status reports server storage.
Once a metadata database has gone over its share of the limit, disk_usage.metadata_trim (one
entry per environment, experimental) reports the last trim pass: bytes before and after (and the
used size, the file less its free pages), records
cleared per tier, the longest hold of the metadata lock, and, while the file is over its share,
reason (busy, needs_gc, live_run, nothing_eligible or vacuum_deferred, null otherwise; Disk Use: The metadata database says exactly what null means) and when the next pass may start
(next_attempt). It is read from the state file; status runs no trim.
The UI’s /state node array does no additional disk-accounting work.
Status inspection reuses bounded evidence instead of re-reading unchanged artifact bytes. Local file identities include device, inode, size, mtime and ctime; changed or missing local copies and directory-store objects are checked again immediately. Cloud availability and remote shape observations can be up to five minutes old; cache hits do not extend that window. Local materialization changes, confirmed transfers, credential changes and Python import-environment changes invalidate the affected evidence. Inspection prefers an already verified local copy for shape. This is availability and shape evidence, not a new freshness proof. Required reads, transfers and server ledger publication keep their direct verification paths.
Local inspection evidence is reusable only after the file’s change timestamp is at least one second old. Recently changed files are read directly without retaining evidence, so inode reuse within a filesystem timestamp tick cannot preserve an old observation.
The disposable inspection cache is limited to 8 MiB and 8192 entries per environment, with at most 64 KiB per value. Corruption, eviction or an unwritable cache causes another check; a busy cache-write lock is skipped. Cold inspection still hashes selected local copies and plain-directory store objects once, so its cost grows with their bytes. These limits do not resolve the broader cold/per-key planning and inspection gaps (#655 and #656).
See also: barca status, The Cache, Remote Storage, Disk Use.
The same text is in your terminal: barca docs status-fields.