Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.moss.dev/llms.txt

Use this file to discover all available pages before exploring further.

​
Error reference

ErrorCauseFix
UnauthorizedMissing or invalid credentialsSet MOSS_PROJECT_ID and MOSS_PROJECT_KEY in your environment
Index not foundQuerying or loading an index that doesn’t existCall createIndex() first; verify the name matches exactly (case-sensitive)
Index not loadedCalling query() before loadIndex()Call loadIndex(name) before query(). Both SDKs fall back to cloud if the index isn’t loaded locally
Index already existsCalling createIndex() on an existing index nameUse addDocs() with upsert: true to update documents, or delete the index first
Missing embeddings runtimeInvalid or unrecognised modelIdUse moss-minilm, moss-mediumlm, or custom
Embedding requiredUsing modelId: 'custom' without providing embeddingSupply an embedding array on every document and every query() call
custom model not supportedCalling createIndexFromFiles with modelId: 'custom'Use moss-minilm or moss-mediumlm; server-side parsing generates embeddings automatically
Job failedAsync mutation errorInspect JobStatusResponse.error via getJobStatus(jobId)

​
Common scenarios

​
Search results are irrelevant

  • Try hybrid search: lower alpha for more keyword matching (default is 0.8): 
    await client.query('my-index', 'query text', { topK: 5, alpha: 0.5 })
  • Check document chunking: very long documents dilute embedding signal. Aim for 200-500 tokens per chunk.
  • Switch models: try moss-mediumlm for 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.
  • createIndexFromFiles() throws if files is empty, exceeds 20 files, or modelId is "custom".
If a job reaches "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?