---
title: "Troubleshooting"
source: "https://docs.vertesiahq.com/content/view-experiences/troubleshooting"
markdown: "https://docs.vertesiahq.com/llms/content/view-experiences/troubleshooting.md"
---

# 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 facet is empty

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 numeric range or date facet does nothing

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](/content/view-experiences/search#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](/content/view-experiences/search#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](/content/search).

## 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/` route, which has no application registry — the component falls back
to the built-in renderer for that section. See
[Custom renderers](/content/view-experiences/embedding#custom-renderers).