Error catalog
Every error carries a stable code, a message, an exit_code, and when a fix exists, a hint that is a runnable command.
| Exit code | Meaning | Typical codes | What to do |
|---|---|---|---|
| 1 | Processing failed | processing_failed, io_error | Read the message; re-run with -v; report with the sidecar if it persists. |
| 2 | Usage or parameter error | invalid_argument, output_exists, path_not_allowed | Fix the flag named in the message; ferraus docs <command> lists every option. |
| 3 | Input missing or unreadable | input_not_found, not_found, permission_denied | Check the path and permissions. |
| 4 | Unsupported format or codec | unsupported_format | Convert first, or install FFmpeg: ferraus doctor --install-ffmpeg. |
| 5 | Model not cached and downloads disabled | model_not_cached | Run the ferraus models pull ... command in the hint, or allow downloads with -y. |
| 6 | Model download or verification failed | download_failed, checksum_mismatch | Retry; the download resumes. A repeated mismatch means a corrupted mirror. |
| 7 | Plugin crashed, timed out, or was not found | plugin_crashed, plugin_timeout, plugin_not_found | Run ferraus plugin scan; try another preset; the main process is unaffected. |
| 8 | Cancelled | cancelled, timeout | Raise --timeout/--max-memory or re-run. |
| 9 | Output verification failed (checksum, clipping guard, duration mismatch) | verification_failed | The output failed a check (hash, clipping, duration). See the message. |
| 10 | Network error | network_error | Check connectivity, or use --offline with cached models. |
| 70 | Internal error (bug) | internal_error | A bug: report it at https://github.com/djynnius/ferraus/issues with the command and sidecar. |