Vector troubleshooting
Diagnose provider, schema, and query issues across the supported vector backends.
Use this page when vector indexes are defined but the backend rejects setup, writes, or queries.
The vector definition is not found
| Likely cause | Fix |
|---|---|
The file is outside src/vectors/** or server/vectors/**. | Move the definition into the discovery directory for the current framework surface. |
The name passed to getVector() does not match the file path. | Check the derived vector name and use that exact string. |
The provider rejects the query or write
| Likely cause | Fix |
|---|---|
| The app is using a different provider than you expect. | Set vector.provider explicitly and recheck provider-specific config. |
| Dimensions or metadata do not match the stored index shape. | Recheck the definition and the target provider setup. |
Embedding generation does not behave as expected
| Likely cause | Fix |
|---|---|
| The definition does not provide an embedding generator. | Add an embedding.generate() function or pass raw vectors yourself. |
| The input shape does not match the embedding function. | Recheck the definition and the payload you pass in. |
Still stuck
- Re-run the setup from Quickstart.
- Recheck the provider page for the active backend.
- Use Runtime API to confirm the handle method and type names.