Troubleshooting

This article lists common errors when 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 also include an errors array with field-level details.

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 are authenticated and can see the search store, but lack the permission for the requested action, for example when you change access_policy on a public store that you do not own.
Solution: Check which store you are targeting and who owns it; see Multi-user isolation and sharing.

Cause: The search store, file, workflow, or run does not exist. The API also returns 404 for stores you cannot access, so that unauthorised callers cannot determine whether a store exists.
Solution: Check the ID and confirm that it belongs to the search store you are targeting.

Cause: The embedding configuration (models) in your create request maps to a collection that is not provisioned. The response includes the derived collection name.
Solution: List the provisioned collections 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 upload sizes and the amount of content 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 the current one is refused. The response contains 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 does not free space immediately: its bytes count until the retention purge erases them. Read the store’s current usage with GET /api/v1/search-stores/<store-id>/usage, or ask a platform admin to raise the limit. The platform returns 409 instead of 413 because the error is caused by the store’s usage, not by the size of the request.

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 always apply. 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 cannot be disabled.

Cause: You requested usage from 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 does not match the workflow’s expected schema.
Solution: Before you submit a run, check the workflow’s schema with pharia sherlock workflows get; see Ingesting files.

Cause: Large files, high concurrent load, or an unsupported file format.
Solution: For large batches, follow the run’s event stream with pharia sherlock runs watch. You can reconnect at any time, because the stream replays the history. For failures, confirm that 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 on your uploaded files first; see Ingesting files.

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