Skip to main content
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

Queries failing or slow

Timeouts, execution errors, multi-stage engine failures, sudden latency increases, error-rate spikes.

Data not arriving

Real-time ingestion stopped or lagging, batch and minion tasks failing, tasks that never got scheduled.

Resource pressure

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.
1

Is the table healthy?

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. A failing TABLE_SEGMENT_AVAILABILITY_CHECK or BROKER_RESOURCE_CHECK points at Queries failing.See Table Health Dashboard & Alerting for how to read the dashboard, and 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.
2

Is it one table, or everything?

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 is usually the better starting point.
3

What changed?

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.
4

Is it constant or intermittent?

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

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.