Skip to main content
RAG is a three-step flow — upload → embed → search — and most issues come from acting before a step finishes. See RAG for the full guide.

​
Upload ‘works’ but the file is empty / not searchable

Uploading is two calls: POST /v1/files registers the file and returns a signed_url; you then PUT the actual bytes to that URL.
  • If you skip the PUT (or it failed), the file exists but has no content.
  • The PUT goes to storage directly — don’t send your Authorization header on it.

​
‘signed_url’ rejected / expired

The signed_url expires within a few minutes. PUT your bytes immediately after registering the file. If it expired, register the file again to get a fresh URL.

​
Search returns nothing right after upload

Embedding is asynchronous. A file is only searchable once embedding_status is ready.
  • Poll GET /v1/files/{file_id} until embedding_status is ready (it moves pending → queued → processing → ready).
  • If it’s failed, re-trigger with POST /v1/files/embed (pass "wait": true to block for small files).
  • If embed: false was set at upload, embedding never started — trigger it manually.

​
Search returns irrelevant or too few results

  • Raise top_k (1–50, default 5).
  • An over-restrictive filter (metadata is exact match) or date_from/date_to window can exclude everything — loosen them.
  • A too-narrow file_ids list restricts search to those files only; omit it to search all your files.
  • Metadata filters only match keys you set at upload time.

​
422 on upload

Check required fields on POST /v1/files — file_name and mime_type (e.g. application/pdf, text/plain, text/markdown). The mime_type also drives file-type detection.

​
Still stuck?

See the Mesh API error reference or email contact@meshapi.ai.