Errors
SDK error codes reference
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 |
|---|---|---|
INVALID_RESPONSE_TYPE | 50001 | Invalid response type received, expected: … |
INVALID_OPERATION_IN_RESPONSE | 50002 | Invalid operation type in response |
STREAM_ENDED_WITHOUT_RESPONSE | 50003 | Stream ended without receiving final response |
INVALID_AUDIO_CHUNK_TYPE | 50004 | Invalid audio chunk type received |
INVALID_TOOLS_ARRAY | 50005 | Invalid tools array provided |
INVALID_TOOL_SCHEMA | 50006 | Invalid tool schema: … |
OCR_FAILED | 50007 | OCR operation failed… |
RPC_NO_HANDLER | 50200 | No handler function registered for request type: … |
RPC_REQUEST_NOT_SENT | 50201 | Cannot perform operation - request has not been sent yet |
RPC_RESPONSE_STREAM_NOT_CREATED | 50202 | Cannot perform operation - response stream not created |
RPC_CONNECTION_FAILED | 50203 | RPC connection failed: … |
PROVIDER_START_FAILED | 50400 | Failed to start provider… |
PROVIDER_STOP_FAILED | 50401 | Failed to stop provider… |
DELEGATE_NO_FINAL_RESPONSE | 50402 | No final response received from delegated provider |
DELEGATE_PROVIDER_ERROR | 50403 | Delegated provider error: … |
DELEGATE_CONNECTION_FAILED | 50404 | Failed to connect to delegated provider: … |
SDK_NOT_FOUND_IN_NODE_MODULES | 50600 | QVAC SDK not found in node_modules. Checked: @qvac/sdk, @tetherto/sdk-mono, @tetherto/sdk-dev |
WORKER_FILE_NOT_FOUND | 50601 | Worker file not found at … |
CONFIG_FILE_NOT_FOUND | 50602 | Config file not found. Searched: …. Create qvac.config.json, qvac.config.js, or qvac.config.ts in your project root. |
CONFIG_FILE_INVALID | 50603 | Config file at … is invalid: … |
CONFIG_FILE_PARSE_FAILED | 50604 | Failed to parse config file at …: … |
CONFIG_VALIDATION_FAILED | 50605 | Config validation failed: … |
PEAR_WORKER_ENTRY_REQUIRED | 50606 | No plugins registered. Pear apps must spawn … as the worker entry. Run \ |
MULTIPLE_SDK_INSTALLATIONS | 50607 | Multiple QVAC SDK installations found: …. Remove all but one to avoid conflicts. |
PROFILER_INVALID_CAPACITY | 50800 | Ring buffer capacity must be at least … |
Server errors
Thrown by the server (model operations, downloads, cache, RAG). Access via SDK_SERVER_ERROR_CODES.{ERROR_NAME}.
| Error | Code | Summary |
|---|---|---|
MODEL_ALREADY_REGISTERED | 52001 | Model with ID "…" is already registered |
MODEL_NOT_FOUND | 52002 | Model with ID "…" not found |
MODEL_NOT_LOADED | 52003 | Model with ID "…" is not loaded |
MODEL_IS_DELEGATED | 52004 | Model "…" is a delegated model and cannot be accessed directly |
UNKNOWN_MODEL_TYPE | 52005 | Unknown model type: …. If using a custom worker bundle, ensure the plugin for "…" is included in your qvac.config plugins array and rebuild with "npx qvac bundle sdk". |
MODEL_LOAD_FAILED | 52200 | Failed to load model… |
MODEL_FILE_NOT_FOUND | 52201 | Model file not found: … |
MODEL_FILE_NOT_FOUND_IN_DIR | 52202 | … model file … not found in directory … |
MODEL_FILE_LOCATE_FAILED | 52203 | Failed to locate … model file: … |
PROJECTION_MODEL_REQUIRED | 52204 | Projection model source is required for multimodal LLM models |
VAD_MODEL_REQUIRED | 52205 | VAD model source is required for this configuration |
TTS_ARTIFACTS_REQUIRED | 52208 | TTS (Chatterbox) requires ttsTokenizerSrc, ttsSpeechEncoderSrc, ttsEmbedTokensSrc, ttsConditionalDecoderSrc, and ttsLanguageModelSrc |
TTS_REFERENCE_AUDIO_REQUIRED | 52209 | TTS (Chatterbox) requires referenceAudioSrc (path or URL to a WAV file for voice cloning) |
PARAKEET_ARTIFACTS_REQUIRED | 52210 | Parakeet model sources are missing. TDT requires parakeetEncoderSrc, parakeetDecoderSrc, parakeetVocabSrc, parakeetPreprocessorSrc. CTC requires parakeetCtcModelSrc, parakeetTokenizerSrc. Sortformer requires parakeetSortformerSrc. |
MODEL_UNLOAD_FAILED | 52400 | Failed to unload model… |
EMBED_FAILED | 52401 | Failed to generate embeddings… |
EMBED_NO_EMBEDDINGS | 52402 | No embeddings returned from model |
TRANSCRIPTION_FAILED | 52403 | Transcription failed… |
AUDIO_FILE_NOT_FOUND | 52404 | Audio file not found or not accessible: … |
TRANSLATION_FAILED | 52405 | Translation failed… |
COMPLETION_FAILED | 52406 | Completion failed… |
ATTACHMENT_NOT_FOUND | 52407 | Attachment not found at path: … |
CANCEL_FAILED | 52408 | Failed to cancel operation… |
TEXT_TO_SPEECH_FAILED | 52409 | Text-to-speech operation failed… |
CONFIG_RELOAD_NOT_SUPPORTED | 52410 | Model "…" does not support hot config reload |
MODEL_TYPE_MISMATCH | 52411 | Model type mismatch: expected "…", got "…" |
OCR_FAILED | 52412 | OCR operation failed… |
IMAGE_FILE_NOT_FOUND | 52413 | Image file not found or not accessible: … |
INVALID_IMAGE_INPUT | 52414 | Invalid image input type provided |
RAG_SAVE_FAILED | 52800 | Failed to save embeddings… |
RAG_SEARCH_FAILED | 52801 | Failed to search embeddings… |
RAG_DELETE_FAILED | 52802 | Failed to delete embeddings… |
RAG_UNKNOWN_OPERATION | 52803 | Unknown RAG operation: … |
RAG_HYPERDB_FAILED | 52804 | HyperDB RAG operation failed: … |
RAG_WORKSPACE_MODEL_MISMATCH | 52805 | Workspace "…" is configured for model "…", but you're trying to use model "…". Use a different workspace or the same model |
RAG_WORKSPACE_NOT_FOUND | 52806 | RAG workspace not found: … |
RAG_WORKSPACE_IN_USE | 52807 | RAG workspace '…' is currently in use. Close it first. |
RAG_WORKSPACE_CLOSE_FAILED | 52808 | Failed to close RAG workspace… |
RAG_LIST_WORKSPACES_FAILED | 52809 | Failed to list RAG workspaces… |
RAG_CHUNK_FAILED | 52810 | Failed to chunk documents… |
RAG_WORKSPACE_NOT_OPEN | 52811 | RAG workspace '…' is not open |
FILE_NOT_FOUND | 53000 | File not found: … |
DOWNLOAD_CANCELLED | 53001 | Download was cancelled |
CHECKSUM_VALIDATION_FAILED | 53002 | Checksum validation failed for … |
HTTP_ERROR | 53003 | HTTP error: … … |
NO_RESPONSE_BODY | 53004 | No response body received from HTTP request |
RESPONSE_BODY_NOT_READABLE | 53005 | Response body is not readable |
NO_BLOB_FOUND | 53006 | No blob found for … |
DOWNLOAD_ASSET_FAILED | 53007 | Failed to download asset… |
SEEDING_NOT_SUPPORTED | 53008 | Seeding is only supported for hyperdrive models |
HYPERDRIVE_DOWNLOAD_FAILED | 53009 | Hyperdrive download failed: … |
INVALID_SHARD_URL_PATTERN | 53010 | URL does not contain a valid sharded model pattern: … |
ARCHIVE_EXTRACTION_FAILED | 53011 | Failed to extract archive: … |
ARCHIVE_UNSUPPORTED_TYPE | 53012 | Unsupported archive type: … |
ARCHIVE_MISSING_SHARDS | 53013 | Archive is missing required shard file: … |
PARTIAL_DOWNLOAD_OFFLINE | 53014 | Cannot resume partial download (… bytes downloaded) - unable to connect. URL: … |
REGISTRY_DOWNLOAD_FAILED | 53015 | Registry download failed: … |
DELETE_CACHE_FAILED | 53200 | Failed to delete cache… |
INVALID_DELETE_CACHE_PARAMS | 53201 | Invalid deleteCache parameters - provide either modelId or cacheKey |
CACHE_DIR_NOT_ABSOLUTE | 53202 | Cache directory must be an absolute path |
CACHE_DIR_NOT_WRITABLE | 53203 | Cache directory is not writable: …… |
SET_CONFIG_FAILED | 53350 | Failed to set config… |
CONFIG_ALREADY_SET | 53351 | Config has already been set and is immutable. Config can only be set once during SDK initialization. |
FFMPEG_NOT_AVAILABLE | 53500 | FFmpeg is not available on this system |
AUDIO_PLAYER_FAILED | 53501 | Audio player failed: … |
INVALID_AUDIO_CHUNK_TYPE | 53502 | Invalid audio chunk type |
DELEGATE_NO_FINAL_RESPONSE | 53700 | No final response received from delegated provider |
DELEGATE_CONNECTION_FAILED | 53701 | Failed to connect to delegated provider: … |
DELEGATE_PROVIDER_ERROR | 53702 | Delegated provider error: … |
RPC_NO_DATA_RECEIVED | 53703 | No data received from request |
RPC_UNKNOWN_REQUEST_TYPE | 53704 | Unknown request type received: … |
PLUGIN_NOT_FOUND | 53850 | Plugin not found for model type "…". If using a custom worker bundle, ensure the plugin is included in your qvac.config plugins array and rebuild with "npx qvac bundle sdk". |
PLUGIN_HANDLER_NOT_FOUND | 53851 | Handler "…" not found in plugin "…" |
PLUGIN_REQUEST_VALIDATION_FAILED | 53852 | Request validation failed for handler "…"… |
PLUGIN_RESPONSE_VALIDATION_FAILED | 53853 | Response validation failed for handler "…"… |
PLUGIN_ALREADY_REGISTERED | 53854 | Plugin already registered for modelType: … |
PLUGIN_HANDLER_TYPE_MISMATCH | 53855 | Handler "…" is …, but was called as …. Use invokePlugin() for reply handlers and invokePluginStream() for streaming handlers. |
PLUGIN_LOGGING_INVALID | 53856 | Plugin "…" has invalid logging configuration: … |
PLUGIN_DEFINITION_INVALID | 53857 | Plugin definition invalid for "…": … |
PLUGIN_MODEL_TYPE_RESERVED | 53858 | modelType "…" is reserved for built-in plugins |
PLUGIN_LOAD_CONFIG_VALIDATION_FAILED | 53859 | modelConfig validation failed for "…": … |
PATH_TRAVERSAL | 53900 | Path traversal detected: "…" escapes base directory "…" |
QVAC_MODEL_REGISTRY_QUERY_FAILED | 53950 | QVAC model registry query failed… |