Skip to content

Exit codes ​

Every swath command exits with one of these codes. The run report (--report FILE) and, inside a dataset directory whose run did not commit, error.json carry the same code with its class and cause.

CodeClassMeaningResumable
0okthe command did what it was asked: the dataset is committed, the text rows or totals are written, or the reader closed stdout early (| head: complete false, stop_reason downstream_closed); also swath resume on a dataset that is already complete–
1fatala failure a person fixes: credentials that do not load or are refused (auth), access denied (access_denied), a disk that fails or turned read-only, no such bucket (not_found), a bucket in another region (region_redirect), another swath process owning the output, an invalid page from the service (cause protocol), more than 100,000 parts (part_limit), an output layout swath did not make (unsafe_layout), more prefixes than --max-prefixes (prefix_limit), more files with several hard links than swath du --max-inodes (inode_limit); for a dataset in a bucket, another run's manifest created first (lost_race), a retained part changed in the bucket (remote_altered), a saved manifest an earlier attempt may still create naming other parts (candidate_mismatch)as resumable says: yes for a journaled run once the cause is fixed (auth, access_denied, a disk error); no for not_found and region_redirect (the fix is another command), another process's output, and the causes named here (protocol marks the journal unresumable)
2usage, refusedusage: the command line does not parse, names an unknown scheme or a malformed SOURCE URL (s3://, az://ACCOUNT without a container), or gives a value out of range (--sort-buffer below 128KiB). refused: something the caller must fix before anything runs: a non-empty -o directory without --overwrite, --overwrite on a directory that is not a swath dataset, a new run over an interrupted one, an output that is or contains the listed tree, --overwrite of an output inside it, a resume whose identity changed or that has nothing to resume, an S3 directory bucket, a bucket or container -o whose prefix already holds a dataset or overlaps the listed sourcerefused changes no part and no journal: an interrupted run there can still be resumed. A resume refused because the run's identity changed (an endpoint taken from the environment, say) rewrites error.json with the refusal (class refused, resumable true); a command refused before any run starts, such as a non-empty -o or a resume given an option that is fixed for the run, changes nothing
3incompletethe run finished, but its output is partial (complete false): entries could not be read (permissions; the dataset's coverage.unreadable and the report's outcome.unreadable count them); or the dataset that swath du --from-dataset or swath resume reads is a finalized diagnostic sample, which stopped early (stop_reason max_keys). The rows, totals or dataset are written (a dataset is committed, without error.json: its manifest's coverage says what is missing); the closing line on stderr says why (partial: …), and under -q, which prints no closing line, an error line says it. swath resume on such a dataset exits 3 againno: fix the cause and run again
74disk_fulla part, a journal record or the manifest could not be written: the filesystem or the quota is full (ENOSPC, EDQUOT; cause no_space); or listing waited on a full spill cap for --spill-wait-timeout (cause spill_budget)yes, once there is space
75stuck, unresolvedstuck: no progress for --stall-timeout (10 minutes by default; a warning at half). unresolved (cause commit_unresolved): a dataset in a bucket whose manifest's creation could neither be confirmed nor refuted; every part is keptyes
124deadline--max-duration reached before the output was finishedyes
129terminatedSIGHUP: the terminal or SSH session closed (stop_source sighup). Under nohup, which ignores it, the run goes onyes
130interruptedSIGINTyes
143terminatedSIGTERMyes

"Resumable" means a dataset run of an object store, whose journal is intact: swath resume DIR continues it. A local tree, text output and swath du keep no journal and are run again.

After SIGINT, SIGTERM or SIGHUP swath stops and records its outcome, then on Linux and macOS dies by that signal, as any command a signal stops: a shell reports 130, 143 or 129 and a shell loop around swath stops too, while a program that waits for it sees the signal (Python's returncode is -2, -15 or -1). The report and error.json say 130, 143 or 129. On Windows the process exits with the code. A forced exit after a signal (below) ends the same way.

A crash. Exit 2 with no outcome (no swath: outcome line with -v, no outcome event, no report) is not a usage error: the Go runtime ended the process, on a panic or on SIGQUIT (kill -QUIT prints every goroutine's stack and exits 2). Nothing was recorded, as after a kill: treat it as one, and swath resume DIR continues a journaled run.

The cause of exit 75 says what rose while nothing progressed:

CauseWhat it means
stuck_throttlethe service kept throttling
stuck_timeoutsrequests kept running past --request-timeout
stuck_empty_chainthe service kept answering empty pages with a new continuation token
stuck_no_rowsnone of these: requests failing or hanging, or a stopped pipeline
unreachablefound early: nothing in the run has answered, and every connection was refused, its host not found or unroutable for 30 s (at most half --stall-timeout); the message names the endpoint. A run that had published no part removes its journal and work files and writes no error.json (resumable false): the corrected command runs on the same -o

A service that only fails or throttles before the listing starts (Azure Blob's namespace check) is asked again the same way, and stops as stuck too, never refused.

The other causes are the provider's failure class (auth, access_denied, not_found, region_redirect, throttle, timeout, parse, unsupported), protocol, no_space, spill_budget, the limits named above, and a dataset in a bucket's commit_unresolved, lost_race, remote_altered and candidate_mismatch. A destination that keeps failing an upload past its retries ends the run fatal; its journal is intact, and swath resume DIR continues it once the destination answers.

What a supervisor does with each code ​

ExitDo
0done
3the output is usable but partial: accept it, or fix the permissions and run again
129, 130, 143swath resume DIR (with --report NEW-FILE to keep its report)
75resume once (unreachable and not resumable: fix the endpoint and run the command again); a second 75 in a row on the same output needs a person (with stuck_empty_chain, the service no longer moves past a point in the key space). unresolved: resume, which creates the same manifest again; without a journal (a local tree written to a bucket), a person checks whether the prefix holds a manifest before deleting anything there
74free space, or move the directory to a larger disk, then swath resume DIR; spill_budget: swath resume DIR --spill-budget SIZE with a larger cap, on a disk with room for it (a plain resume keeps a recorded --spill-budget; with the default cap it derives one from the free space it finds). With the default cap, growing the disk under the running process avoids the stop: the cap follows it
124resume only within a separate budget of attempts or total time: a source that keeps a run busy without finishing reaches 124 on every attempt; past the budget, a person
1a person fixes the cause; then swath resume DIR when the outcome is resumable, else a new run
2a person fixes the command; with no outcome or report, a crash: as a kill, swath resume DIR

Give every unattended attempt a --max-duration, and set the supervisor's own kill deadline above --max-duration plus 20 seconds: after a stop swath waits up to 15 seconds for the run to stop, then records its outcome and exits, at most 20 seconds after the stop. An attempt killed by the supervisor may have no report; treat its outcome as unknown, never as the one in an older error.json.

The outcome of record ​

The outcome of an attempt is its exit code plus its report: for a dataset run, DIR/run.json beside the committed dataset or DIR/error.json (below); with --report FILE, the whole report of every attempt (on failure too). Give each attempt a fresh path outside the output directory: swath resume writes a report only when given --report, never to the path the run recorded. The report's outcome has class, exit_code, resumable, cause, complete (nothing is missing from the output), stop_reason, and attempt.id names the attempt (Run report and progress file).

DIR/error.json holds the same outcome inside a dataset directory whose run did not commit (beside the previous dataset, for an --overwrite run that did not replace it):

json
{
  "class": "deadline",
  "exit_code": 124,
  "message": "deadline: --max-duration reached",
  "resumable": true,
  "stop_source": "timebox",
  "attempt": {
    "id": "5c3c3d59be9ea1c21fa747cc8b647131",
    "started_at": "2026-11-10T12:35:34.390093Z"
  },
  "run": {
    "id": "0d4e8f6a2b1c4d3e9f8a7b6c5d4e3f2a"
  },
  "status": "failed",
  "complete": false
}

It is current only when its attempt.id is the report's: an attempt that could not write it (another process owned the output, the disk refused the write) leaves the previous one, and says why in the report's outcome.unrecorded. error.json is removed when a later run or resume commits the dataset (exit 0 or 3).

A usage error or refusal (exit 2), and a failure before any request was answered (a missing bucket or directory, credentials that do not load), print one line on stderr and no closing lines:

text
swath: nosuchdir: no such file or directory

How swath classifies and records an outcome, and its liveness rules: Run lifecycle (internals).

Released under the Apache-2.0 license · by Varve