Error reference
| Error | Cause | Fix |
|---|---|---|
Unauthorized | Missing or invalid credentials | Set MOSS_PROJECT_ID and MOSS_PROJECT_KEY in your environment |
Index not found | Querying or loading an index that doesn’t exist | Call createIndex() first; verify the name matches exactly (case-sensitive) |
Index not loaded | Calling query() before loadIndex() | Call loadIndex(name) before query(). query() throws if the index isn’t loaded locally |
Index already exists | Calling createIndex() on an existing index name | Use addDocs() with upsert: true to update documents, or delete the index first |
Missing embeddings runtime | Invalid or unrecognised modelId | Use moss-minilm, moss-mediumlm, or custom |
Embedding required | Using modelId: 'custom' without providing embedding | Supply an embedding array on every document and every query() call |
Job failed | Async mutation error | Inspect JobStatusResponse.error via getJobStatus(jobId) |
Common scenarios
Search results are irrelevant
- Try hybrid search: lower
alphafor more keyword matching (default is0.8): - Check document chunking: very long documents dilute embedding signal. Aim for 200-500 tokens per chunk.
- Switch models: try
moss-mediumlmfor higher accuracy.
SDK error behaviour
- Most methods throw if the target index does not exist.
createIndex()throws if the index already exists.loadIndex()throws if the index does not exist in cloud storage or loading fails.
"failed", its JobStatusResponse.error will be non-null. The job’s currentPhase (see JobPhase) can hint at where it failed - a job stuck on downloading usually means a network issue.
Still stuck?
- Join the Moss Discord for community help
- Open an issue on GitHub