Troubleshooting by feature

The symptom guides narrow a problem down to a subsystem. This page takes you the rest of the way: it indexes the troubleshooting, FAQ and limitations material that lives on individual feature pages, so you do not have to know which page it is on.

Feature-specific troubleshooting is deliberately kept next to the feature it belongs to, alongside the configuration and concepts it refers to. This page is a directory, not a copy.

Streaming ingestion

If you are dealing with	Go to
Consumption stalls, segment commit and ordering behaviour, and the debug APIs for inspecting consuming segments	Pauseless consumption → Operational Troubleshooting, and Debugging APIs
Which log lines indicate which consumption problem	Key logging patterns for debugging
Records failing to decode, or a schema-registry problem	The decoder’s own page: Glue · OpenTelemetry · Prometheus remote write · Pulsar key-value Avro
Change-data-capture pipelines behaving unexpectedly	MongoDB CDC · Debezium CDC recipe
Kinesis-specific questions	Kinesis FAQs
Pulsar connection problems	Pulsar recipe

Batch ingestion and minion tasks

If you are dealing with	Go to
Tasks not being scheduled, queue behaviour, concurrency and retries	Minion task orchestration → FAQs
Purge tasks failing or not removing what you expect	Purge task, FAQs & Recommendations section
Backfill not producing the segments you expect	Segment backfill task, FAQs & Recommendations section
The real-time to offline flow not running	Managed offline flow recipe
JFR record ingestion	JFR record reader
A file preview failing during table creation	Preview from file → Troubleshooting

Upserts and dedup

If you are dealing with	Go to
Duplicate rows, or counts running ahead of the source	Diagnosing duplicates and count mismatches — includes `skipUpsert`, the `$segmentName` / `$docId` / `$hostName` virtual columns, and detecting cross-replica divergence
Compaction or segment refresh tasks failing on an upsert table	Upsert operations guide → Troubleshooting
Offline upsert constraints	Offline upserts → Limitations

Queries, indexes and performance

If you are dealing with	Go to
Interpreting what Query Analyzer told you, including its internal diagnostic values	Reading Query Analyzer results → Diagnostic Values
A slow geospatial query	Geospatial performance → Troubleshooting performance issues
Checking what a reload would do before running it, or a dry run that failed	Reload dry run → Troubleshooting
A star-tree index that is not being used	StarTree index recipe → Troubleshooting
An index-inference apply that failed	Index inference apply → Troubleshooting
Queries being throttled or starved by other workloads	Memory-throttled scheduler → Troubleshooting
Materialized view behaviour	Multi-stage materialized views → FAQs
`JSON_EXTRACT_INDEX` returning unexpected results	json_extract_index → Error handling
Gaps in what `system_query_log` captures	Query Logger, Limitations & caveats section

Segments and storage

If you are dealing with	Go to
Hitting a segment-count limit, or wanting to see where a table stands	Segment count limits → Monitoring and troubleshooting
Columnar segment processing failures	Columnar segment processing → Troubleshooting
Deep-store sync behaviour and constraints	Deep store sync → Limitations
A self-managed MinIO deep store	MinIO deep store recipe
Understanding what storage a table is consuming	Table storage usage

External tables

External tables have the most developed troubleshooting material in the docs — External table troubleshooting is organised by symptom and indexed by the exact error string to search for, covering onboarding, schema and table creation, queries, and sync operations. Start there for anything external-table shaped.

If you are dealing with	Go to
A specific external-table error string — region errors, `Access Denied`, `NumberFormatException`, `servers not responded`, distributed-lock failures	External table troubleshooting
Operational problems, including ZooKeeper packet-size overflow as segment count grows	Operational guidance → Additional troubleshooting
General questions and behaviour	External tables FAQ
Monitoring sync state, lag and freshness	External table observability
A type not mapping as you expect	Data type mapping → Known limitations
Deletion vector or segment group behaviour	Deletion vectors → FAQs · Segment groups → FAQs
Catalog-specific constraints	The `Limitations` section on your catalog’s onboarding page — Glue · Unity · Polaris · Nessie · S3 · S3 Tables · GCS

Security and access

If you are dealing with	Go to
Audit logs not appearing or not containing what you expect	Pinot audit logs → Troubleshooting
Row-level policies not filtering as intended	Row-level access control → Limitations
Working out which action governs an operation	RBAC actions

Interfaces and integrations

If you are dealing with	Go to
Elasticsearch-compatible queries	Elasticsearch gateway → Troubleshooting and its Limitations
Semantic search behaviour	Semantic search → Troubleshooting
The MCP server	StarTree MCP → Limitations
Generative AI recipes	GenAI recipe → Troubleshooting

Scaling and cluster operations

If you are dealing with	Go to
A scheduled scaling operation that did not take effect	Scheduled server scaling → Troubleshooting and its Notes and limitations
Cluster-, broker-, controller- or minion-level health checks	Cluster Health Dashboard

ThirdEye

ThirdEye has its own troubleshooting section under its own tab:

Not finding what you need here? Work through the symptom guides instead — they start from what you are seeing rather than from which feature is involved, which is the better route when you do not yet know what is at fault.

Get Started

Ingestion

External Tables

Query Data

Manage Data

Observability

Visualize Data

Cluster Operations

Manage Security

Release Notes

Reference

Troubleshooting by feature

Streaming ingestion

Batch ingestion and minion tasks

Upserts and dedup

Queries, indexes and performance

Segments and storage

External tables

Security and access

Interfaces and integrations

Scaling and cluster operations

ThirdEye

​Streaming ingestion

​Batch ingestion and minion tasks

​Upserts and dedup

​Queries, indexes and performance

​Segments and storage

​External tables

​Security and access

​Interfaces and integrations

​Scaling and cluster operations

​ThirdEye

Streaming ingestion

Batch ingestion and minion tasks

Upserts and dedup

Queries, indexes and performance

Segments and storage

External tables

Security and access

Interfaces and integrations

Scaling and cluster operations

ThirdEye