> ## Documentation Index
> Fetch the complete documentation index at: https://docs.startree.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Troubleshooting: start here
> Start here when something is wrong. Identify the symptom, follow the matching guide, and know what to collect before you open a support ticket.
Most production problems in StarTree Cloud fall into a small number of shapes. There is a diagnostic path for each, using only what you can see and do yourself from the Data Portal, the Query Console, and the APIs your cluster exposes. Each one lives with the part of the product it concerns — queries under Query Data, ingestion under Ingestion, capacity under Cluster Operations. This page routes you to the right one.
If you already know the shape of the problem, go straight to the relevant guide. If you do not, work through **Triage** below — it takes about two minutes and will tell you which guide to open.
## Choose a guide
Timeouts, execution errors, multi-stage engine failures, sudden latency increases, error-rate spikes.
Real-time ingestion stopped or lagging, batch and minion tasks failing, tasks that never got scheduled.
Out-of-memory conditions, high CPU, servers filling up, degradation after an upgrade or a traffic peak.
## Triage
Answer these in order. The first one that matches tells you where to go.
Open **Observability → Health Dashboard** in the Data Portal and find the affected table. Failing checks name the subsystem in trouble, which is usually enough to pick a guide.
A failing `TABLE_INGESTION_CHECK` points at [Data not arriving](/corecapabilities/ingestdata/troubleshooting). A failing `TABLE_SEGMENT_AVAILABILITY_CHECK` or `BROKER_RESOURCE_CHECK` points at [Queries failing](/corecapabilities/query_data/troubleshooting).
See [Table Health Dashboard & Alerting](/corecapabilities/observability/table-health-and-alerting) for how to read the dashboard, and [Cluster Health Dashboard](/corecapabilities/cluster-operations/use-cluster-health-dashboard) for cluster-wide checks.
Not every failing check is a fault. Some checks are best-practice recommendations that do not apply to every deployment — a check that flags a configuration you deliberately chose is telling you about a convention, not an outage. Read the check description before acting on it.
Run a trivial query (`SELECT 1`) and then a `SELECT COUNT(*)` against an unrelated table.
If both succeed, the problem is scoped to one table or one query pattern — start with the table's health checks. If the trivial query also fails or hangs, the problem is cluster-wide, and [Resource pressure](/corecapabilities/cluster-operations/troubleshooting) is usually the better starting point.
The overwhelming majority of sudden production changes follow a change somewhere. Before investigating deeply, check whether any of these happened recently:
* A cluster or engine version upgrade
* A table config, schema, or index change
* A change in your upstream source — new schema version, different partition count, a producer deploy
* A change in query volume or shape from your application
* A rebalance, reload, or scaling operation
A symptom that started at the same time as one of these is very likely caused by it, and saying so in a support ticket saves a round trip.
A constant failure is usually configuration, schema, or capacity. An intermittent failure is usually contention, a specific data shape, or one unhealthy replica.
For intermittent problems, note whether failures correlate with a time of day, a particular query, or a particular tenant — that correlation is often the whole diagnosis.
## Tools you will use
| Tool | What it answers | Where |
| ---------------------- | ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| **Health Dashboard** | Is this table structurally healthy right now? | Data Portal → Observability |
| **Query Console** | Does this query still fail, and what does it return? | Data Portal → Query Console |
| **Query Analyzer** | Why is this query slow, and how should it be rewritten or indexed? | Data Portal → Query Console → Analyze. See [Query Analyzer](/corecapabilities/query_data/query-analyzer) |
| **`system_query_log`** | What did the cluster actually serve, how long did it take, and what errored? | Query Console, as an ordinary table. See [Query Logger](/corecapabilities/query_data/advanced_operations/query-logger) |
| **Task views** | Did my ingestion or maintenance tasks run, and what did they do? | Data Portal → Tasks. See [Task Observability](/corecapabilities/observability/task-observability) |
Query Logger is not enabled by default. If `system_query_log` does not exist on your cluster, contact StarTree Support to have it enabled — it is the single most useful diagnostic surface for query problems, and it only captures traffic from the point it is switched on. Enabling it before you need it is worth doing.
## Before you open a support ticket
A ticket that arrives with this information attached is typically resolved in one exchange rather than three. Collect what applies:
* Cluster and environment, and the table name including its `_OFFLINE` / `_REALTIME` suffix
* When the problem started, in a stated timezone, and whether it is ongoing
* Whether it is constant or intermittent, and what fraction of requests are affected
* What changed recently — see step 3 of Triage
* The business impact, and whether a workaround is in place
* The full query text, unedited
* The complete error message, including any nested cause
* The `requestId` from the response, or from `system_query_log`
* Whether the query uses the single-stage or multi-stage engine
* Whether the same query previously worked, and roughly when it last did
* If you have Query Logger enabled, the row from `system_query_log` for a failing execution
* How far behind the data is, and whether the gap is growing, flat, or shrinking
* Whether every partition is affected or only some
* Any recent change to the upstream topic, stream, or source bucket — including partition count and schema version
* For batch and minion tasks: the task type, the task or plan ID, and the failure message
* Whether the table paused consumption, and whether it was paused deliberately
* Which component is under pressure — server, broker, controller, or minion
* Whether the pressure is memory, CPU, or disk
* When it began, and whether it coincided with a traffic change or an upgrade
* Your current tenant sizing and whether it has changed recently
Where a support engineer would ask "can you reproduce it," answering that in the first message is the biggest single accelerator. A query that fails every time is far faster to diagnose than one that failed once yesterday.
## What these guides do not cover
These pages cover problems you can diagnose from your own cluster. Some classes of problem are visible only to StarTree Operations — control-plane faults, telemetry pipeline outages, and infrastructure events in the managed layer. If you have worked through the relevant guide and the symptom does not match anything in it, that is a meaningful diagnostic result in itself, and worth stating in your ticket.