Skip to main content

Troubleshooting

This page covers common Query Builder issues and the current behavior behind them.

API Returns 401 Unauthorized​

Check the API token and request header.

The request must include:

Authorization: Bearer your-api-token

Also confirm that:

  • The token belongs to a user with guard_name = api.
  • The API user account is active.
  • The token has not been copied with extra spaces or missing characters.

API Returns 404 Not Found​

A 404 means OSPROV could not find the query endpoint.

Check that:

  • The query slug in the URL matches the saved query.
  • The URL is encoded correctly.
  • The query was not deleted.

The query name is part of the endpoint URL, so use the exact API URL shown in the Query Builder list.

Filters Are Not Applied​

If saved filters appear to be ignored, check whether the API request includes filters[...] URL parameters.

When any URL filter is present, all saved filters are replaced for that request. URL filters do not merge with saved filters.

Also confirm that the field key in the request matches the submission field key exactly. Field keys are case-sensitive.

Null Filters Do Not Save​

Is Null and Is Not Null appear in the UI, but they are not reliably saved in the current version because the save logic requires a non-empty filter value.

Use URL parameters for null checks:

GET /api/query/{name}?filters[optionalField]=is_null
GET /api/query/{name}?filters[optionalField]=is_not_null

Aggregation Shows 0 or an Unexpected Value​

Check that the aggregated field contains numeric values in the matching submissions. Aggregations only process numeric values, and non-numeric values are skipped.

Also check whether the same field has both a filter and an aggregation configured. If both are configured, the aggregation takes priority and the filter is discarded when saved.

If you are looking at preview results, call the full API endpoint before confirming the total.

Preview Totals Look Wrong​

This is expected in the current version.

Preview limits results to 2 rows before calculating total_matches and aggregate. Use preview to confirm field keys and response shape, then call the full API endpoint for accurate totals.

Preview also uses saved filters and aggregates only. Save the query before previewing changes.

Query Is Slow​

Query Builder loads matching submissions for the selected workflow into memory and applies filters in PHP.

To improve response time:

  • Add a date range filter.
  • Avoid unfiltered queries on workflows with thousands of submissions.
  • Select only the fields needed by the consuming report or integration.
  • Batch external API calls by date range.
  • Run high-volume integrations during off-peak hours.

Field Does Not Appear in Data Fields​

If a field is missing from the Data Fields dropdown, check that:

  • The workflow is published.
  • The form has been saved with field labels.
  • The workflow includes the field in its combined_labels configuration.

After updating the workflow or form, save or republish as needed and check the dropdown again.

Checkbox Filters Do Not Work Reliably​

Checkbox fields show Is True and Is False options in the UI, but those options are not reliably saved in the current version.

Avoid depending on saved checkbox filters until this behavior changes.

Time Field Filtering Is Unexpected​

Time filters use date-level boundaries internally, from start of day to end of day. They are not true time-only filters.

If precise time filtering is required, validate the result through the API with known test submissions before using the query in production.

Query Name Cannot Be Changed​

The query name becomes the API URL slug and is locked after saving. This protects existing integrations from broken URLs.

To use a different endpoint name, create a new query with the desired name and update API consumers to use the new URL.

Deleted Query Endpoint Stops Working​

Deleting a query permanently removes it and immediately disables its API endpoint.

If an integration starts returning 404 after deletion, recreate the query or update the integration to use another saved query endpoint.