Troubleshooting

This article lists problems you may encounter while integrating with the Data and Search Platform, and how to resolve them.

In this article:

Error response shape

The Data and Search Platform returns errors as RFC 7807 problem details:

{
  "title": "Not Found",
  "status": 404,
  "detail": "SearchStore not found"
}

Validation failures additionally include an errors array with field-level detail.

Cause: Missing or invalid authorisation token.
Solution: Log in again with the platform CLI (pharia iam login) — see Log in with the platform CLI.

Cause: You’re authenticated, but don’t have the required permission for an action on a search store you can otherwise see (for example, trying to change access_policy on a public store without being its owner).
Solution: Confirm which store you’re targeting and who owns it — see Multi-user isolation and sharing.

Cause: The search store, file, workflow, or run doesn’t exist — this is also returned for stores you can’t access, so existence isn’t leaked to unauthorised callers.
Solution: Double-check the ID and that it belongs to the search store you’re targeting.

Cause: The embedding configuration (models) you specified when creating a search store derives a collection name that isn’t provisioned yet. The response includes the derived name.
Solution: List what exists with GET /api/v1/collections and use one of those configurations, or ask a platform admin to provision yours with POST /api/v1/collections — see how search stores are stored.

A deployment can limit what you upload and what a search store holds — see Storage and page limits.

Cause: The search store is at or past max_storage_bytes (on upload) or max_pages_per_search_store (on run submission). The platform checks the limit before each operation, so the operation that crossed the limit completed and this one is refused. The response carries limit_key, limit, current_usage, scope, and unit — in details on the upload route, and in errors[0].value on the run route.
Solution: Erase content you no longer need, then retry. Deleting a file is not enough on its own: the bytes count until the retention purge erases them. Read the store’s current position with GET /api/v1/search-stores/<store-id>/usage, or ask a platform admin to raise the limit. The platform returns 409 rather than 413 here, because the request is not too big — the store is too full.

Cause: The file is larger than max_file_size, or the whole upload request is larger than max_upload_request_size. Both default to 100 MiB and are always in force. A file past max_file_size gets a problem detail with the type /errors/file-too-large. A request past max_upload_request_size is refused by the HTTP server before it reaches the API, so that response carries no body.
Solution: Send fewer files per request, or ask a platform admin to raise the limit. These two limits can never be unlimited.

Cause: You read usage on a deployment that has no usage accounting configured, such as a server that serves an unpacked export.
Solution: Read usage against the main deployment instead.

Cause: The input passed to a workflow run doesn’t match its expected schema.
Solution: Check the workflow’s schema first with pharia sherlock workflows get before submitting a run — see Ingesting files.

Cause: Large files, high concurrent load, or an unsupported file format.
Solution: For large batches, stay on the run’s event stream with pharia sherlock runs watch (watching again is safe — it replays history); for failures, confirm the file format is supported (PDF, DOCX, PPTX, XLSX, or images) — see Ingesting files.

Cause: The search store has no indexed chunks yet.
Solution: Run an ingestion workflow against your uploaded files first — see Ingesting files.

Cause: An invalid filters object in a search request.
Solution: This returns 400 Bad Request, not a server error — check the operator syntax against Filtering results.