Errors | Rinne

Rinne stops when it cannot guarantee a correct result. CLI failures print a message and return a structured exit code so the cause can be handled safely by a person or script.

What to try first

Confirm the terminal or GUI opened the intended workspace.
Confirm the requested space, snapshot, path, or Activity selector exists.
Retry after the current operation finishes or close another Rinne process holding the database or workspace lock.
Run the relevant verification command when integrity is mentioned: verify, repair verify, or activity verify.
Check permissions, free disk space, and filesystem health for I/O failures.

Exit codes

v0.9.7 uses the unified exit-code set across CLI commands. Desktop workflows map cancellation and failure states to the same categories where applicable.

Code	Name	Meaning
`0`	Success	The command completed successfully.
`1`	Failure	General command failure.
`2`	UsageError	Invalid arguments, options, dates, or selectors.
`3`	BusyOrLocked	Another operation is running or a required database or workspace lock is held.
`4`	NotFound	Required workspace, space, snapshot, path, stored object, or Activity entry was not found.
`5`	SafetyBlocked	A required safety condition or explicit confirmation was not satisfied.
`6`	CheckFailed	Integrity, validation, verification, or precondition checks failed.
`99`	Fatal	Unexpected fatal error.
`130`	Canceled	The operation was canceled, including Ctrl+C cancellation.

Common causes

Workspace not found: The current directory does not contain .rinne/, or required workspace metadata is missing.
Space, snapshot, or path not found: The requested object does not exist. Rinne does not silently create missing history state.
Busy or locked: Another command or desktop operation is using the workspace or SQLite database.
Ignored by rinneignore: The selected path is excluded by rinneignore.json.
Permission, path, or storage failure: Access denied, read-only files, disk full, device errors, or OS path limits prevented the operation.
Integrity problem: Snapshot, repair, CAS, or Activity verification detected inconsistent or damaged data.

Activity-specific cases

Invalid subcommand, option, number, or date

Returns UsageError. --skip must be zero or greater; --limit must be one or greater and is clamped to maxListLimit.

Selector out of range or no id match

activity show returns NotFound when an @n index is outside the history or no UUID/prefix matches.

Ambiguous short id

A prefix matching more than one entry returns UsageError and prints matching ids. Supply more UUID characters.

Clear without --force

activity clear requires the exact --force argument and otherwise returns UsageError.

Unreadable settings or database I/O

Activity management commands report filesystem, permission, locking, and SQLite failures. The desktop Activity window also exposes read states such as missing data, broken settings, unsupported schema, busy/locked, and read error.

Hash-chain verification failed

activity verify prints each detected issue and returns CheckFailed (6).

Canceled

Cancellation returns 130 and prints that the Activity command was canceled.

A failure while appending Activity for another CLI command is different: recording uses bestEffort, so that logging failure is suppressed and the original command's result is preserved. A directly invoked rinne activity ... management operation still reports its own failure normally.

Reporting

Include the full error message, exact command line, operating system, and whether another Rinne CLI or GUI process was using the workspace. Remove secrets before sharing command lines or logs.

Early Access note: messages may evolve. The v0.9.7 exit-code categories are intended to remain script-friendly.