Command lineExit codes and errors
Exit codes and errors
What each census exit code means, every error code it can report, and what to do about each one.
Exit codes
| Code | Status | Meaning |
|---|---|---|
0 | ok, complete | Done. A query succeeded, a scan completed, or a cleanup deleted everything it could. Skipped items are normal. |
1 | failed | A bad request: arguments, a selection, a missing confirmation. Nothing was deleted. |
2 | failed | An operational failure: a scan failed, another cleanup was running, the Trash couldn’t be read. |
4 | partial | Partly done: some folders couldn’t be read, some items couldn’t be fully deleted, or a maintenance task failed. |
7 | not_found | No saved result: no scan, no review set, or the path or app isn’t in the scan. |
130 | cancelled | Ctrl-C or SIGTERM stopped it. |
141 | — | stdout closed early (SIGPIPE), as in census top | head -1. Nothing is printed. |
With --json, the same number is in the envelope’s exit_code, and errors says why.
Handle errors in a script
census clean --safe --json > result.json
case $? in
0) jq -r '"Freed \(.results.freed_bytes) bytes"' result.json ;;
4) jq -r '.results.items[] | select(.outcome.result == "failed" or .outcome.result == "partial") | .path.display' result.json ;;
7) echo "No saved scan. Run: census scan" >&2 ;;
*) jq -r '.errors[0].message' result.json >&2 ;;
esac
Error codes
Every failure has a code in errors[].code and a message meant for people.
| Code | Exit | What happened | What to do |
|---|---|---|---|
invalid_request | 1 | A misspelled command or option, a bad value, or an option given twice. For example unknown command: tpo (did you mean top?). | Fix the arguments. census help COMMAND lists a command’s options. |
ambiguous_app | 1 | The app name matches more than one app. | Use the app’s bundle ID. |
output_exists | 1 | export --output names a file that exists. | Pick another path, or add --force. |
confirmation_required | 1 | A command that deletes ran without a terminal and without --safe or --yes. | Pass the flag once the person has agreed. |
invalid_selection | 1 | A path in the selection file, or a PATH argument, isn’t one census listed. Nothing was deleted. | Copy paths exactly from review --json, duplicates --json or large --json. |
review_stale | 1 | The review set, duplicate search or Large Files listing is more than 7 days old. | Run census review --json (or the search) again. |
run_as_root | 1 | A cleanup ran with sudo. | Run it as yourself. |
cache_unreadable | 2 | The saved scan couldn’t be read. | Scan again. |
busy | 2 | In census serve, another long job is running. | Wait for it, then send the request again. |
scan_failed | 2 | The scan couldn’t run. | Read the message. |
output_failed | 2 | export couldn’t write the report. | Check the path and its permissions. |
selftest_failed | 2 | A self-test scenario failed. | See selftest. |
cleanup_running | 2 | Another cleanup is running. | Wait for it to finish. Don’t retry in a loop. |
cleanup_failed | 2 | The cleanup couldn’t run. | Read the message. |
trash_unreadable | 2 | A Trash couldn’t be read, so nothing was deleted. | Give the app that runs census Full Disk Access. |
partial_scan | 4 | Some folders couldn’t be read. | See read_errors in the scan’s JSON. Full Disk Access often helps. |
partial_cleanup | 4 | Some items couldn’t be fully deleted. | Check each item’s outcome. |
maintenance_failed | 4 | A maintenance task failed. The others still ran. | Check the task’s result and detail. |
no_review | 7 | There is no review set, duplicate search or Large Files listing to apply. | Run census review --json first. |
no_cache | 7 | There is no saved scan for the scope. | Run census scan. |
path_not_scanned | 7 | The path isn’t in the saved scan. | Scan a scope that includes it. |
apps_not_scanned | 7 | The scan doesn’t include your apps. | Run census scan, the whole drive. |
home_not_scanned | 7 | The scan doesn’t include your home folder. | Run census scan, the whole drive. |
app_not_found | 7 | No installed app matches the name. | Check the name with census apps. |
cancelled | 130 | The command was stopped. | What was deleted so far is in the audit log. |
Uninstall errors
census uninstall adds a few codes of its own:
| Code | Exit | What happened |
|---|---|---|
app_running | 1 | A program inside the app is still running, so nothing was deleted. census never quits apps. Quit it and try again. |
needs_admin | 1 | The app has a folder you can’t change, or a locked or SIP-protected entry. |
system_app | 1 | The app is part of macOS. |
not_removable | 1 | The app can’t be removed. |
app_not_removed | 4 | The app wasn’t fully deleted, so its data was left as it was. EPERM usually means macOS’s App Management protection: allow the app that runs census in System Settings › Privacy & Security. |
Scan read errors
A scan’s read_errors describes paths it couldn’t read. It is scan data, separate from errors. Each recorded path has a code:
| Code | Meaning | Makes the scan partial |
|---|---|---|
sip_protected | Protected by System Integrity Protection. | No |
root_only | Owned by root, and its permissions deny you. sudo can include it. | No |
other_owner_private | Owned by another user or service account. | No |
os_protected | macOS keeps it from every app, even with Full Disk Access. | No |
full_disk_access_required | Needs Full Disk Access, which this process doesn’t have. | Yes |
access_denied | Denied for another reason, including your own folder without read permission. | Yes |
path_disappeared | Removed between listing and reading. | No |