barca history
After verifying that the process or container has stopped, explicitly reconcile an uncertain
row with barca history --reconcile RUN_ID --json. This records only that row as
interrupted and prints it in the normal history envelope (runs, total: 1,
truncated: false); --fields and human output also work. It refuses a proven live owner,
a terminal row, an unknown id, and combining --reconcile with --limit or --all.
It preserves recorded step counts, successful materializations and artifacts, and leaves
unknown end time and duration as null. It does not stop a process. Ordinary history reads
still keep an uncertain owner running; reconciliation is your assertion that it stopped.
The change is local to the selected environment’s metadata database.
barca history [RUN_ID] [--status S] [--target NAME] [--triggered-by T] [--not-triggered-by T] [--search TEXT] [--since WHEN] [--until WHEN] [--activity] [-l N | --all] [--json|--pretty]barca history --reconcile RUN_IDShow recent runs from .barca/metadata.db: run id, command, target, status, step counts and
timing. TARGET is the run’s job by function name, all for a run without targets, cut at 24
characters with ….
The human table defaults to the 10 most recent; JSON returns every run unless --limit is explicit.
$ barca historyRUN_ID CMD TARGET STATUS STEPS CACHED TIME STARTED------------------------------------------------------------------------------------------------------14f1e316840c run notify success 1 2 0.1s 2026-10-21 02:39:25 UTC14f01f296a75 get country_report,weekly_s… success 0 2 0.0s 2026-10-21 02:39:25 UTC14f3870e173f get all success 2 0 0.1s 2026-10-21 02:39:25 UTCTimes are UTC. --fields takes run_id, command, files, target, job, status,
steps_total, steps_executed, steps_cached, attempts, started_at, finished_at,
elapsed_seconds, triggered_by, scheduled_at, schedule_id, client_run_id, failure, failed_node, error, principal, trigger_reason, cancellation. triggered_by says what
started the run: manual (a command typed on a machine), api (an HTTP request to
barca serve), schedule (a cron tick, with the tick in scheduled_at, RFC 3339 in UTC, and
the scheduled node in schedule_id) or client; it is null for runs recorded before barca
recorded it. job is the run’s job in full: all, or its resolved node ids sorted and
comma-separated (null for runs recorded before 0.29.0); target is the target as typed.
barca history --fields run_id,triggered_by,scheduled_at # what started each runbarca history -l 25 # last 25; human default 10, JSON default every runbarca history --json # {"runs": [...], "total": N, "truncated": bool, "hint"?: "..."}barca history --fields run_id,status # JSON with only these keys per runHistory JSON returns every run unless --limit N is explicit; the human table defaults to 10.
When more runs exist than are shown, the JSON has "truncated": true, the total, and a hint;
the table prints the same hint as one line on stderr. See Bounded output. Each
run’s files is an array of the .py files it was given.
Terminal status and successful/failed step rows commit together. Required database-write failures report an infrastructure error and preserve previous progress/history and run state, which normally remains unfinished. Captured output is written separately after that transaction.
Mid-run database writes commit completed-step rows and their progress count together. Failed batches are retained and retried without waiting for another step; replay does not count a completed step twice. Progress can be absent while the database cannot commit. The final write still records completed results not saved during execution.
Finding and reading a failed run
Section titled “Finding and reading a failed run”Filters combine with AND, and --limit, total and truncated count the runs they keep:
--status (comma-separated: success, failed, cancelled, error, running,
interrupted; not_successful is every one but success and running), --target NAME
(the run’s target or job is that node; runs of every node are left out), --triggered-by
(comma-separated: manual, api, schedule, client), --not-triggered-by (the same
values, left out: schedule hides the cron ticks and keeps the runs recorded before barca
stored what started a run), --search TEXT (the run id, target or job contains the text,
whatever its case), --since (30m, 24h, 7d, 2w, an RFC 3339 time or a UTC date) and
--until (started before a time, written the same way; with --since, a window). The
database keeps the runs, each filter from an index, so a filter costs the runs it keeps and
not the runs recorded. A failed run’s row ends
with its first failed step and the first line of its error; JSON runs carry it as
failure: {node, error} and as the flat failed_node and error (null otherwise), so
--fields run_id,failed_node,error needs no nesting.
barca history --status failed --since 24hbarca history --target clean --triggered-by schedule --jsonbarca history --status not_successful --not-triggered-by schedulebarca history --search daily_report --since 7dbarca history 836fdca186c8 # one run in detailbarca history 836fdca186c8 --json # {run, steps: [...], hint?}Runs in progress and the last day’s activity
Section titled “Runs in progress and the last day’s activity”With --status running, each listed run that is in progress says what it is working on now
(experimental): a now: executing 3: orders, clean, report · 12 waiting · 240/900 keys line
under its row, and in JSON now (running, queued, keys, groups, line), the object
the web UI’s run panel shows. The server counts the nodes its workers are executing. A separate CLI
process publishes no worker assignments, so its unfinished targets appear in the waiting count.
barca history --activity prints, instead of the runs, how many started in each of the last
24 hours (experimental), by status and by what started them, with each hour’s median time and
what most of its unsuccessful runs say went wrong, counted over every recorded run of the
window whatever --limit would list. JSON is {"activity": {since, until, triggered_by, not_triggered_by, statuses, search, hours, total, excluded, summary}}; hours are hours of
UTC. It takes --status, --triggered-by, --not-triggered-by and --search:
--not-triggered-by schedule leaves a schedule’s runs out and says in excluded how many
that was.
barca history --status runningbarca history --status running --json --fields run_id,nowbarca history --activitybarca history --activity --not-triggered-by schedule --jsonThe full key list and the limits are in status, “Runs in progress and the last day’s activity”.
barca history RUN_ID prints the run’s fields, the steps it recorded (status, attempts, time,
peak memory, run hash, artifact path, format and size), and for each failed step its error,
traceback, when the worker died how it ended (worker exit: SIGKILL (possibly the OOM killer)), and the last 20 lines it printed (output_tail in JSON, without the traceback).
Each step’s JSON has max_rss_bytes, the worker process’s peak resident memory while the step
ran (on Linux the step’s own; elsewhere only when the step raised the worker’s peak), and
cpu_seconds. Bytes DuckDB spilled to disk are not recorded: DuckDB keeps no total of them. A hint on
stderr names barca logs RUN_ID --step STEP --stream stderr. Cached steps are counted in
steps_cached, not listed: a run records no row for them. With a server configured, both
forms answer from the server; a run only this machine has is an error whose remediation is
barca history RUN_ID --local.
The run also says why it executed what it did. In JSON, run.plan_reasons is the record
(never_run, new_keys, failed (the last attempt at these inputs failed), code_changed /
inputs_changed / env_changed with the component that changed
(helper pipelines/common.py:bucket_ltv), a refresh, a missing artifact, a task or a sensor),
and explanation is the same in words: why groups the steps by the reason they ran,
attempts counts retries apart from each step’s first attempt (29 steps, no retries),
targets lists the run’s targets, target_outcomes says what became of each, and a run in
progress has progress with an ETA at the rate so far. The table prints it: the attempts on
the first line, and after the steps: line a why: line, then each reason with the nodes and
steps that ran for it (the first eight of a reason). A group whose nodes each ran one step is
counted in nodes, with an example. The reasons are recorded as the run decides each phase, so a
run in progress shows the phases decided so far. A run started on a server also shows who
asked for it (as token:<name>, principal), the reason: its request gave, and, when
cancelled, why (cancelled: ..., cancellation). GET /runs/{run_id} carries the same
explanation, which the web UI renders. Details: CLI contract.
why: 5,492 steps ran: 5,000 new partition keys, 31 code changed, 3 input changed new partition keys 5,000 steps of 1 node: invoices_by_account code changed 29 nodes: helper billing.py:_n 2 nodes: code input changed 3 nodes: billing.py:dunning_05$ barca history 836fdca186c8run 836fdca186c8 get clean failed 0.1s 1 step, no retriesstarted 2026-10-22 22:57:27.000 UTC finished 2026-10-22 22:57:27.000 UTCtriggered by apifiles pipeline.pysteps: 1 executed (1 failed), 1 cached (cached steps are not listed)why: 1 step ran: 1 never run never run 1 node: clean
STEP STATUS ATTEMPTS TIME RUN_HASH ARTIFACTpipeline.py:clean failed 1 - d64e1b00647e -
pipeline.py:clean failed: ZeroDivisionError: division by zero Traceback (most recent call last): File "/srv/pipelines/pipeline.py", line 11, in clean return [{"id": o["id"], "per_unit": 10 / o["qty"]} for o in orders] ~~~^~~~~~~~~~ ZeroDivisionError: division by zerohint: barca logs 836fdca186c8 --step clean --stream stderrA run’s status is running, success, failed, cancelled or interrupted. A run records
each step as it finishes, so a running run already counts them in steps_executed, and
barca status from another terminal shows them as cached. A run whose process was killed is
interrupted (no finished_at); the next barca get reuses the steps it had recorded. A run
killed in a container is interrupted too, once a container starts again on the same .barca
volume (from 0.20.0; earlier versions left it running). For runs started with 0.20.0 or later, a run stays running
whenever barca cannot establish that its process is gone. Earlier runs retain their legacy
process-id and host-name checks. See
Where Things Live: While a run is going, and after one is killed, and the shared-state
limitations.