Troubleshooting

Most View problems come down to a field name that does not match the index, a property type that was never mapped, or a configuration that saved but cannot execute. This page lists the common cases.

A terms facet returns no values.

Wrong field path. The field must match the indexed path exactly, for example properties.status. Inspect real values before configuring a facet — the Studio editor's preview and Studio Assistant's inspect_view_data both show actual buckets.
Not a keyword field. Facets aggregate on keyword-typed fields. Property strings are keywords by default, but a field that was mapped as text (or is numeric) will not aggregate as a term facet.
Nothing in scope matches. The View's scope (or an active navigation selection) may exclude every document that has the property. Widen the scope or clear other selections to confirm.

A range facet or a numeric/date sort has no effect.

This is almost always a typed indexing problem. Property strings map to keyword, and date-looking strings stay keywords — so a range or date control over them cannot work until the field is mapped with a numeric or date type and the project is reindexed. Store numbers as JSON numbers, declare explicit types in indexing.property_mappings, and run a full reindex. See Typed property indexing.

Remember: changing property_mappings does not rewrite the active index. The new type only applies after a full reindex.

Validation returns HTTP 400 for a query

Creating, updating, previewing, or executing a View returns a 400 that names an unsupported query clause.

The most common cause is a scope.fixed_filter that uses an Elasticsearch query type outside the supported allowlist. Simplify it to supported clauses (bool, term, terms, range, match, exists, prefix, and similar), or move the constraint into scope.type_ids, scope.collection_ids, or scope.locations. Agentic plans go through the same query validator before they can reach Elasticsearch.

A 400 can also come from an out-of-range execution input (for example a non-numeric limit); the returned path and message identify the invalid value.

An old View cannot be saved

Editing an existing View returns a 400 complaining that description is required.

Persisted Views require a non-empty description. Current Studio deployments backfill older records from the View name, but a mixed-version deployment or record that has not yet been migrated can still surface this error. Supply a description in the update payload (or in the Studio editor) and save again.

Agentic search fell back to deterministic

The response search block reports applied_mode: 'deterministic' and a warning even though the View is configured as agentic.

The runtime falls back to deterministic search when query planning times out, fails validation, or does not meet minimum_confidence. Check the warning code in the response. To reduce fallbacks: give the planner a clearer search.fields catalog with good description text, raise timeout_ms, lower minimum_confidence if it is too strict, or refine search.agentic.instructions. The fallback is safe by design — it never runs fuzzy queries outside the validated field catalog.

Full-text search does not match extracted property text

A query that should match text inside a property returns nothing.

Property strings are indexed as keyword, which is exact-match only. For a property whose value is meaningful prose (for example extracted instructions), map the path as text in indexing.property_mappings, reindex, and list it in search.fields with mode: 'full_text'. See Typed property indexing.

Nothing loads / "Elasticsearch is not enabled"

View execution requires Elasticsearch. Enable it for the project and ensure the scoped content is indexed. See Search Configuration.

A custom renderer is not used

You passed a renderers registry but the built-in renderer still shows.

The renderer name on the search, navigation item, or display must match a key in the registry exactly. When a name is missing — including on the generic /view/<id> route, which has no application registry — the component falls back to the built-in renderer for that section. See Custom renderers.