Errors and exit codes
Understand failures, preserved state, and the next recovery step.
Moji writes errors to stderr with the prefix moji:.
Exit codes
| Code | Meaning | Examples |
|---|---|---|
0 | Success | Results printed, dry run completed, download, conversion, or inspection completed |
1 | Operational failure | Provider outage, invalid font content, codec failure, filesystem failure |
2 | Invalid usage | Missing input, unknown flag, unsupported format, conversion pair, or inspection container |
Common failures
No provider completed the search
Check the provider-specific explanations that follow the first sentence. Verify connectivity and provider configuration, then retry. GetFonts remains the fallback when GitHub authentication is unavailable.
In the TUI, press H when the results screen says a provider needs attention.
The Health screen keeps the provider's actual error, wraps long messages, and
names the setting or authentication command to fix. Use j/k to scroll when
the terminal is too short to show every failure.
GitHub search is not configured
Set GITHUB_TOKEN, set github_token in the config, or pass
--token-stdin. Retry with --provider getfonts if GitHub is not needed.
No fonts matched
Try a different family name or remove --weight and --format. No download
was started.
Download was rejected
Moji reports whether it blocked HTTP, exceeded the redirect or size limit, received invalid font content, or found a destination collision. Rejected content remains in a temporary file only until cleanup; no completed font is placed at the destination.
For a single-font request, Moji continues through the ranked candidates and reports an aggregate error only if it cannot reach the requested success count. For an entire-family request, each same-source group is staged and either completed as a unit or discarded before the next group is tried.
Conversion was rejected
Moji detects local font formats from their content. A truncated or malformed
font is an operational failure. A recognized but unsupported conversion pair,
such as TTF-to-OTF or a WOFF2 file whose embedded flavor does not match
--to, is an invalid usage error.
Move or rename an existing destination before retrying. Moji never replaces it. Failed conversion and output operations remove their temporary files, so an error does not leave a partial completed font behind.
Inspection was rejected
Moji inspects TTF, OTF, and WOFF2 fonts. A recognized but unsupported container is an invalid usage error. A malformed font, unreadable input, or character-map parsing failure is an operational error. Inspection never changes the input file.
Config could not be parsed
Fix the YAML at the reported path or move the file aside to use defaults. Moji does not replace an existing config unless the new file was fully written and secured first.
Editor could not open
Set EDITOR or edit the reported path directly. Moji reports whether it
created the default config before trying the editor.