hSUMerror catalog

hSUM / docs / 0.1.0-alpha.1 / errors

Error catalog

64 public subcodes across 18 categories. Every hSUM failure — CLI, CLI JSON, and MCP — names one of these and links here.

INVALID_ARGUMENT

The request was rejected before any work began — an input broke a documented contract. · exit 2

QUERY_EMPTYthe search query is emptyQUERY_SYNTAXthe search query syntax is invalidLIMIT_OUT_OF_RANGEa requested limit is outside the supported rangeCITATION_MALFORMEDthe evidence citation is invalidPOINTER_EXISTSa repository pointer already existsFRAME_LIMITthe protocol request exceeds a framing limitCONFIG_INVALIDthe hSUM configuration is invalidPATH_INVALIDa required filesystem path is invalidPOINTER_INVALIDthe repository pointer is invalidTRUST_REGISTRY_INVALIDthe hSUM trust registry is invalidBROAD_ROOT_CONFIRMATION_REQUIREDthe selected source root requires explicit broad-root confirmationLARGE_SOURCE_CONFIRMATION_REQUIREDthe selected source exceeds the default initialization budgetEMPTY_SNAPSHOT_CONFIRMATION_REQUIREDreplacing a nonempty source with an empty snapshot requires confirmationMASS_DELETE_CONFIRMATION_REQUIREDthe snapshot exceeds the mass-deletion confirmation thresholdTRUST_CONFIRMATION_REQUIREDcreating a repository trust binding requires confirmationINDEX_PATH_OCCUPIEDthe managed index path is already occupiedUNSUPPORTED_STORAGEthe selected index storage is unsupportedUNSUPPORTED_PLATFORMthis operation is unsupported on the current platform

NOT_FOUND

The target could not be located in the authorized index or project. · exit 1

INDEX_NOT_FOUNDthe selected hSUM index is unavailablePROJECT_NOT_FOUNDthe selected hSUM project is unavailableEVIDENCE_NOT_FOUNDthe requested evidence is unavailableSCOPE_HIDDENthe requested evidence is unavailable

EVIDENCE_FORGOTTEN

The cited evidence was deliberately forgotten and cannot be resolved. · exit 1

FORGET_TOMBSTONEthe cited evidence was explicitly forgotten

MODEL_MISSING

A required local embedding model is not configured or not installed. · exit 3

MODEL_NOT_CONFIGUREDthis index has no configured modelMODEL_NOT_INSTALLEDthe configured model is not installed

MODEL_INCOMPATIBLE

The local model does not match this index's pinned contract. · exit 3

MODEL_FINGERPRINTthe local model is incompatible with this indexMODEL_DIMENSIONthe local model is incompatible with this index

DOWNLOAD_FAILED

A model download did not complete or failed verification. · exit 3

NETWORK_TRANSIENTthe model download failed temporarilyretryCHECKSUM_MISMATCHthe downloaded model checksum is invalid

PERMISSION_DENIED

The operating system or trust policy denied a required file access. · exit 7

SOURCE_READhSUM cannot read the selected sourceINDEX_WRITEhSUM cannot write the managed indexPATH_TRUSTthis repository is not bound to an hSUM project

RESOURCE_EXHAUSTED

A disk, quota, or memory budget would be exceeded. · exit 7

DISK_SPACEthere is not enough free disk spaceINDEX_QUOTAthe managed index quota would be exceededMEMORY_BUDGETthe request exceeds the memory budget

INDEX_BUSY

Another writer or the model worker is busy — retry after the reported backoff. · exit 4

WRITER_LOCKanother process is mutating this indexretryMODEL_QUEUEthe local model worker is busyretryMODEL_RESTARTINGthe local model worker is busyretry

INDEX_CORRUPT

The index file is not a valid or self-consistent hSUM database. · exit 5

APPLICATION_IDthe selected file is not an hSUM indexSCHEMA_CHECKSUMthe hSUM index schema checksum is invalidSQLITE_CORRUPTSQLite reports index corruption

INTEGRITY_FAILED

Internal evidence indexes disagree — a structural integrity check failed. · exit 5

HEAD_INDEX_MISMATCHactive evidence indexes are out of parityFORGET_LEDGER_MISMATCHthe forget ledger does not match the index

STALE_CURSOR

A pagination cursor no longer matches current index state. · exit 1

INDEX_EPOCHthe search cursor is staleGENERATIONthe search cursor is staleSCOPE_REVISIONthe search cursor is staleQUERY_FINGERPRINTthe search cursor is stale

TIMEOUT

Bounded work did not finish before its deadline. · exit 4

REQUEST_DEADLINEthe request deadline expiredretryDRIFT_PROBEthe live-source probe timed outretry

CANCELLED

The client cancelled or disconnected before completion. · exit 130

CLIENT_CANCELLEDthe client cancelled the requestCLIENT_DISCONNECTEDthe client disconnected

SCHEMA_TOO_OLD

The index schema predates this binary and needs migration or upgrade. · exit 5

MIGRATION_REQUIREDthe index requires an explicit schema migrationUPGRADE_REQUIREDthe index requires an intermediate hSUM upgrade

SCHEMA_TOO_NEW

The index was written by a newer hSUM binary than this one. · exit 5

DOWNGRADE_UNSUPPORTEDthe index was created by a newer hSUM binary

SOURCE_INVALID

A source file could not be ingested as valid text. · exit 1

INVALID_UTF8a source file is not valid UTF-8NUL_CONTENTa source file contains NUL bytesFILE_TOO_LARGEa source file exceeds the configured size limitENUMERATION_INCOMPLETEthe filesystem enumeration was incompleteretrySOURCE_CHANGED_DURING_READa source file changed while it was readretry

INTERNAL

An unexpected internal failure — preserve the request ID and run hsum doctor. · exit 1

STORAGE_IOthe managed storage operation failedretrySQLITE_IOSQLite could not complete a storage I/O operationretryINVARIANTan internal evidence invariant failedNONFINITE_SCOREa retrieval backend returned an invalid scoreUNEXPECTEDan unexpected internal failure occurred