Errors

Example

import { SDK_CLIENT_ERROR_CODES, SDK_SERVER_ERROR_CODES } from "@qvac/sdk";

try {
  await loadModel({ modelSrc: "/path/to/model.gguf", modelType: "llm" });
} catch (error) {
  if (error.code === SDK_SERVER_ERROR_CODES.MODEL_LOAD_FAILED) {
    // handle model load failure
  }
}

Client errors

Thrown on the client side (response validation, RPC, provider). Access via SDK_CLIENT_ERROR_CODES.{ERROR_NAME}.

Error	Code	Summary	Thrown by
`INVALID_RESPONSE_TYPE`	50001	Invalid response type received.	`cancel()`, `downloadAsset()`, `embed()`, `getModelInfo()`, `loadModel()`, `loggingStream()`, `ping()`, `ragDeleteEmbeddings()`, `ragSaveEmbeddings()`, `ragSearch()`, `startQVACProvider()`, `stopQVACProvider()`, `unloadModel()`
`INVALID_OPERATION_IN_RESPONSE`	50002	Response operation didn't match the expected RAG operation.	`ragDeleteEmbeddings()`, `ragSaveEmbeddings()`, `ragSearch()`
`STREAM_ENDED_WITHOUT_RESPONSE`	50003	Streaming RPC ended without a final response.	`downloadAsset()`, `loadModel()`, `ragDeleteEmbeddings()`, `ragSaveEmbeddings()`, `ragSearch()`
`INVALID_AUDIO_CHUNK_TYPE`	50004	Invalid audio chunk input type provided.	`transcribe()`, `transcribeStream()`
`INVALID_TOOLS_ARRAY`	50005	Invalid tools array provided.	`completion()`
`INVALID_TOOL_SCHEMA`	50006	Invalid tool schema provided.	`completion()`
`OCR_FAILED`	50007	OCR operation failed.	`ocr()`
`RPC_CONNECTION_FAILED`	50203	RPC connection failed.	Any API call (startup/transport)
`PROVIDER_START_FAILED`	50400	Failed to start provider.	`startQVACProvider()`
`PROVIDER_STOP_FAILED`	50401	Failed to stop provider.	`stopQVACProvider()`
`DELEGATE_NO_FINAL_RESPONSE`	50402	No final response received from delegated provider.	`loadModel()`, `completion()`
`DELEGATE_CONNECTION_FAILED`	50404	Failed to connect to delegated provider.	`loadModel()`, `completion()`
`CONFIG_FILE_PARSE_FAILED`	50604	Failed to import/parse a `qvac.config.*` file.	Any API call (during SDK initialization)
`CONFIG_VALIDATION_FAILED`	50605	Config validation failed (schema mismatch / invalid JSON).	Any API call (during SDK initialization)

Server errors

Thrown by the server (model operations, downloads, cache, RAG). Access via SDK_SERVER_ERROR_CODES.{ERROR_NAME}.

Error	Code	Summary	Thrown by
`MODEL_ALREADY_REGISTERED`	52001	Model with the same ID is already registered.	`loadModel()`
`MODEL_NOT_FOUND`	52002	Model ID not found in the registry.	`completion()`, `embed()`, `getModelInfo()`, `loggingStream()`, `ocr()`, `textToSpeech()`, `transcribe()`, `transcribeStream()`, `translate()`, `unloadModel()`, `ragDeleteEmbeddings()`, `ragSaveEmbeddings()`, `ragSearch()`
`MODEL_NOT_LOADED`	52003	Model exists but is not loaded.	`completion()`, `embed()`, `ocr()`, `textToSpeech()`, `transcribe()`, `transcribeStream()`, `translate()`
`MODEL_IS_DELEGATED`	52004	Model is delegated and cannot be accessed as a local model.	`completion()`, `embed()`, `ocr()`, `textToSpeech()`, `transcribe()`, `transcribeStream()`, `translate()`
`UNKNOWN_MODEL_TYPE`	52005	Unknown `modelType` in `loadModel()`.	`loadModel()`
`MODEL_LOAD_FAILED`	52200	Failed to load model (generic).	`loadModel()`
`MODEL_FILE_NOT_FOUND`	52201	Model file not found at given path.	`loadModel()`
`MODEL_FILE_NOT_FOUND_IN_DIR`	52202	Expected model file not found in directory (e.g., by type).	`loadModel()`
`MODEL_FILE_LOCATE_FAILED`	52203	Failed to locate model file for the given `modelType`.	`loadModel()`
`PROJECTION_MODEL_REQUIRED`	52204	Projection model source is required for multimodal LLM models.	`loadModel()`
`VAD_MODEL_REQUIRED`	52205	VAD model source is required for this configuration.	`loadModel()`
`TTS_CONFIG_MODEL_REQUIRED`	52206	`ttsConfigModelPath` is required for TTS models.	`loadModel()`
`ESPEAK_DATA_PATH_REQUIRED`	52207	`eSpeakDataPath` is required for TTS models.	`loadModel()`
`MODEL_UNLOAD_FAILED`	52400	Failed to unload model.	`unloadModel()`
`EMBED_FAILED`	52401	Failed to generate embeddings.	`embed()`
`EMBED_NO_EMBEDDINGS`	52402	No embeddings returned from model.	`embed()`
`TRANSCRIPTION_FAILED`	52403	Transcription failed.	`transcribe()`, `transcribeStream()`
`AUDIO_FILE_NOT_FOUND`	52404	Audio file not found or not accessible.	`transcribe()`, `transcribeStream()`
`TRANSLATION_FAILED`	52405	Translation failed.	`translate()`
`COMPLETION_FAILED`	52406	Completion failed.	`completion()`
`ATTACHMENT_NOT_FOUND`	52407	Attachment file not found at path.	`completion()`
`CANCEL_FAILED`	52408	Failed to cancel operation.	`cancel()`
`TEXT_TO_SPEECH_FAILED`	52409	Text-to-speech operation failed.	`textToSpeech()`
`CONFIG_RELOAD_NOT_SUPPORTED`	52410	Model does not support hot config reload.	`transcribe()`, `transcribeStream()`
`MODEL_TYPE_MISMATCH`	52411	Model type mismatch (expected vs provided).	`completion()`, `embed()`, `ocr()`, `textToSpeech()`, `transcribe()`, `transcribeStream()`, `translate()`, `ragDeleteEmbeddings()`, `ragSaveEmbeddings()`, `ragSearch()`
`IMAGE_FILE_NOT_FOUND`	52413	Image file not found or not accessible.	`ocr()`
`INVALID_IMAGE_INPUT`	52414	Invalid image input type provided.	`ocr()`
`RAG_SAVE_FAILED`	52800	Failed to save embeddings.	`ragSaveEmbeddings()`
`RAG_SEARCH_FAILED`	52801	Failed to search embeddings.	`ragSearch()`
`RAG_DELETE_FAILED`	52802	Failed to delete embeddings.	`ragDeleteEmbeddings()`
`RAG_WORKSPACE_MODEL_MISMATCH`	52805	Workspace is configured for a different embeddings model.	`ragDeleteEmbeddings()`, `ragSaveEmbeddings()`, `ragSearch()`
`RAG_WORKSPACE_NOT_FOUND`	52806	RAG workspace not found.	`ragDeleteEmbeddings()`, `ragSaveEmbeddings()`, `ragSearch()`
`RAG_WORKSPACE_IN_USE`	52807	RAG workspace is in use and can't be closed/deleted.	`ragDeleteEmbeddings()`, `ragSaveEmbeddings()`, `ragSearch()`
`RAG_WORKSPACE_NOT_OPEN`	52811	RAG workspace is not open.	`ragDeleteEmbeddings()`, `ragSaveEmbeddings()`, `ragSearch()`
`RAG_CHUNK_FAILED`	52810	Failed to chunk input into embeddings.	`ragSaveEmbeddings()`
`DOWNLOAD_CANCELLED`	53001	Download cancelled.	`cancel()`, `downloadAsset()`, `loadModel()`
`CHECKSUM_VALIDATION_FAILED`	53002	Downloaded file checksum validation failed.	`downloadAsset()`, `loadModel()`
`HTTP_ERROR`	53003	HTTP request failed with status code.	`downloadAsset()`, `loadModel()`
`DOWNLOAD_ASSET_FAILED`	53007	Download failed.	`downloadAsset()`, `loadModel()`
`HYPERDRIVE_DOWNLOAD_FAILED`	53009	Hyperdrive download failed.	`downloadAsset()`, `loadModel()`
`INVALID_SHARD_URL_PATTERN`	53010	Invalid shard URL pattern for sharded downloads.	`downloadAsset()`, `loadModel()`
`ARCHIVE_EXTRACTION_FAILED`	53011	Failed to extract an archive.	`downloadAsset()`, `loadModel()`
`ARCHIVE_UNSUPPORTED_TYPE`	53012	Unsupported archive type.	`downloadAsset()`, `loadModel()`
`ARCHIVE_MISSING_SHARDS`	53013	Archive is missing required shards.	`downloadAsset()`, `loadModel()`
`PARTIAL_DOWNLOAD_OFFLINE`	53014	Partial download exists but offline prevents resuming.	`downloadAsset()`, `loadModel()`
`DELETE_CACHE_FAILED`	53200	Failed to delete cache.	`deleteCache()`
`INVALID_DELETE_CACHE_PARAMS`	53201	Invalid parameters for `deleteCache()`.	`deleteCache()`
`CACHE_DIR_NOT_ABSOLUTE`	53202	Cache directory must be an absolute path.	`deleteCache()`
`CACHE_DIR_NOT_WRITABLE`	53203	Cache directory is not writable.	`deleteCache()`
`FFMPEG_NOT_AVAILABLE`	53500	Audio decoding required but FFmpeg is not available.	`transcribe()`, `transcribeStream()`

Example

Client errors

Server errors

On this page