Moss - Real-time Semantic Search for Conversational AI

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)`
`Validation error: index name must not be blank, "." or "..", must not contain "/" or control characters, and must be at most 256 bytes`	An index name that is blank, `.` or `..`, contains `/` or a control character, or is longer than 256 bytes. The SDK rejects it before sending any request	Use a name within these rules. Pass the raw name: the SDK percent-encodes it, so an already encoded name addresses a different index. (Python moss 1.14.0+, @moss-js/moss 1.15.0+, @moss-dev/moss-web 1.3.0+, Elixir moss 1.4.0+, Swift SDK 0.7.0+)

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. With a cachePath (cache_path in Python) and a snapshot already on disk, it serves that snapshot instead when the cloud is unreachable or answers with a temporary error, while a 401, 403 or 404 still throws. (Python moss 1.14.0+, @moss-js/moss 1.15.0+)

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?

Join the Moss Discord for community help
Open an issue on GitHub

Getting Started

Capabilities

Use Cases

How it works

Pricing

Errors & Troubleshooting

Error reference

Common scenarios

Search results are irrelevant

SDK error behaviour

Still stuck?

​Error reference

​Common scenarios

​Search results are irrelevant

​SDK error behaviour

​Still stuck?

Error reference

Common scenarios

Search results are irrelevant

SDK error behaviour

Still stuck?