Error Reference

Error Reference

All error types thrown by the library across all languages.

Error

Errors that can occur when using the tree-sitter language pack.

Covers language lookup failures, parse errors, query errors, and I/O issues. Feature-gated variants are included when config, download, or related features are enabled.

Matching on Error

The set of variants is not stable: new failure modes are added in minor releases, and Io, Json, and Toml exist only under certain feature combinations, so the variant set a downstream crate sees depends on which features it enables. Downstream matches must therefore carry a _ arm; #[non_exhaustive] makes the compiler enforce that instead of letting a feature change silently break a build.

C ABI error codes

Each variant alef can see carries an explicit alef(error_code = N) allocation that becomes a member of the generated AlefFfiErrorCode C enum. These numbers are a public ABI contract: an allocated number is never reused after its variant is removed, and a variant’s number never changes, because C callers compare against the value, not the name. New variants take the next free number. 0-4 are reserved by alef, so allocation starts at 100. An unannotated variant is emitted as the unknown code rather than as itself, which silently flattens the taxonomy — annotate every new variant.

Variant	Message	Description
LanguageNotFound	Language ‘{0}’ not found	The requested language name (or alias) was not found in the registry.
DynamicLoad	Dynamic library load error: {0}	A dynamic shared library could not be loaded at runtime.
NullLanguagePointer	Language function returned null pointer for ‘{0}’	The tree-sitter language function returned a null pointer for the given language name.
ParserSetup	Failed to set parser language: {0}	The language could not be applied to the parser (e.g., ABI version mismatch).
LockPoisoned	Registry lock poisoned: {0}	An internal RwLock or Mutex was poisoned by a previous panic.
Config	Configuration error: {0}	A configuration file or value was invalid or could not be applied.
ParseFailed	Parse failed: parsing returned no tree	The tree-sitter parser returned no tree for the given source input.
ParseTimeout	Parse cancelled: exceeded the configured budget of {timeout_ms} ms	The parse was cancelled because it exceeded its configured wall-clock budget. Raised only when a budget is configured — see ProcessConfig.parse_timeout_ms, which defaults to None.
QueryError	Query error: {0}	A tree-sitter query could not be compiled or executed.
InvalidRange	Invalid byte range: {0}	A byte range was invalid (e.g., end before start, or out of bounds).
Download	Download error: {0}	A parser download from GitHub releases failed.
ChecksumMismatch	Checksum mismatch for ‘{file}’: expected {expected}, got {actual}	The downloaded file’s SHA-256 digest did not match the manifest’s expected value.
CacheLock	Download cache lock error: {0}	The cross-process download cache lock file could not be acquired or created.

---