> ## 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 by feature

> A directory of the feature-specific troubleshooting, FAQ and limitations sections across the documentation, grouped by the problem they solve.

The [symptom guides](/corecapabilities/observability/troubleshooting) 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.

<Info>
  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.
</Info>

## Streaming ingestion

| If you are dealing with | Go to |
| - | - |
| A StarTree alert about ingestion, such as `RealtimeIngestionStopped` or `HighRealtimeIngestionOffsetLag` | [Real-time ingestion alerts](/corecapabilities/observability/alerts/real-time-ingestion) |
| Consumption stalls, segment commit and ordering behaviour, and the debug APIs for inspecting consuming segments | [Pauseless consumption → Operational Troubleshooting](/corecapabilities/ingestdata/adv-concepts/realtime/pauseless-consumption#operational-troubleshooting), and [Debugging APIs](/corecapabilities/ingestdata/adv-concepts/realtime/pauseless-consumption#debugging-apis) |
| Which log lines indicate which consumption problem | [Key logging patterns for debugging](/corecapabilities/ingestdata/adv-concepts/realtime/pauseless-consumption#key-logging-patterns-for-debugging) |
| Records failing to decode, or a schema-registry problem | The decoder's own page: [Glue](/corecapabilities/ingestdata/adv-concepts/realtime/decoders/glue#troubleshooting) · [OpenTelemetry](/corecapabilities/ingestdata/adv-concepts/realtime/decoders/opentelemetry#troubleshooting) · [Prometheus remote write](/corecapabilities/ingestdata/adv-concepts/realtime/decoders/prometheus-remote-write#troubleshooting) · [Pulsar key-value Avro](/corecapabilities/ingestdata/adv-concepts/realtime/decoders/pulsar-key-value-avro#troubleshooting) |
| Change-data-capture pipelines behaving unexpectedly | [MongoDB CDC](/corecapabilities/ingestdata/adv-concepts/realtime/mongodb-cdc#troubleshooting) · [Debezium CDC recipe](/recipes/debezium-cdc#troubleshooting) |
| Kinesis-specific questions | [Kinesis FAQs](/corecapabilities/ingestdata/dataportal/streaming/kinesis#faqs) |
| Pulsar connection problems | [Pulsar recipe](/recipes/pulsar#troubleshooting) |

## Batch ingestion and minion tasks

| If you are dealing with | Go to |
| - | - |
| A StarTree alert about a task, such as `FailedToGenerateFileIngestionTask` or `MinionSubTaskHighWaitTime` | [Batch ingestion and minion task alerts](/corecapabilities/observability/alerts/batch-and-minion-tasks) |
| Tasks not being scheduled, queue behaviour, concurrency and retries | [Minion task orchestration → FAQs](/corecapabilities/ingestdata/adv-concepts/batch/minion-task-orchestration#faqs) |
| Purge tasks failing or not removing what you expect | [Purge task](/corecapabilities/manage-data/purge-task), *FAQs & Recommendations* section |
| Backfill not producing the segments you expect | [Segment backfill task](/corecapabilities/manage-data/segment-backfill-task), *FAQs & Recommendations* section |
| The real-time to offline flow not running | [Managed offline flow recipe](/recipes/managed-offline-flow#troubleshooting) |
| JFR record ingestion | [JFR record reader](/corecapabilities/ingestdata/adv-concepts/batch/jfr-record-reader#troubleshooting) |
| A file preview failing during table creation | [Preview from file → Troubleshooting](/api-reference/table/preview-from-file#troubleshooting) |

## Upserts and dedup

| If you are dealing with | Go to |
| - | - |
| A StarTree alert about an upsert table, such as `HighTotalDocsToPKCountRatio` | [Upsert table alerts](/corecapabilities/observability/alerts/upsert-tables) |
| Duplicate rows, or counts running ahead of the source | [Diagnosing duplicates and count mismatches](/corecapabilities/manage-data/offheap-upsert#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](/corecapabilities/manage-data/upsert-operations-guide#troubleshooting) |
| Offline upsert constraints | [Offline upserts → Limitations](/corecapabilities/ingestdata/adv-concepts/batch/offline-upserts#limitations) |

## Queries, indexes and performance

| If you are dealing with | Go to |
| - | - |
| A StarTree alert about query errors, timeouts, or quota | [Query alerts](/corecapabilities/observability/alerts/queries) |
| Interpreting what Query Analyzer told you, including its internal diagnostic values | [Reading Query Analyzer results → Diagnostic Values](/corecapabilities/ai/query-analyzer/reading-results#diagnostic-values) |
| A slow geospatial query | [Geospatial performance → Troubleshooting performance issues](/corecapabilities/manage-data/indexes/geospatial-performance#troubleshooting-performance-issues) |
| Checking what a reload would do before running it, or a dry run that failed | [Reload dry run → Troubleshooting](/corecapabilities/manage-data/reload-dry-run#troubleshooting) |
| A star-tree index that is not being used | [StarTree index recipe → Troubleshooting](/recipes/startree-index#troubleshooting) |
| An index-inference apply that failed | [Index inference apply → Troubleshooting](/api-reference/table/index-inference-apply#troubleshooting) |
| Queries being throttled or starved by other workloads | [Memory-throttled scheduler → Troubleshooting](/corecapabilities/query_data/advanced_operations/workload-isolation/memory-throttled-scheduler#troubleshooting) |
| Materialized view behaviour | [Multi-stage materialized views → FAQs](/corecapabilities/query_data/materialized-views/multi-stage-materialized-views#faqs) |
| `JSON_EXTRACT_INDEX` returning unexpected results | [json\_extract\_index → Error handling](/corecapabilities/query_data/functions/json_extract_index#error-handling) |
| Gaps in what `system_query_log` captures | [Query Logger](/corecapabilities/query_data/advanced_operations/query-logger), *Limitations & caveats* section |

## Segments and storage

| If you are dealing with | Go to |
| - | - |
| A StarTree alert about replicas, segments in error, or a storage limit | [Data availability and storage alerts](/corecapabilities/observability/alerts/data-availability-and-storage) |
| Hitting a segment-count limit, or wanting to see where a table stands | [Segment count limits → Monitoring and troubleshooting](/corecapabilities/manage-data/recipes/segment-count-limits#monitoring-and-troubleshooting) |
| Columnar segment processing failures | [Columnar segment processing → Troubleshooting](/corecapabilities/manage-data/columnar-segment-processing#troubleshooting) |
| Deep-store sync behaviour and constraints | [Deep store sync → Limitations](/corecapabilities/manage-data/deep-store-sync#limitations) |
| A self-managed MinIO deep store | [MinIO deep store recipe](/recipes/minio-deep-store#troubleshooting) |
| Understanding what storage a table is consuming | [Table storage usage](/corecapabilities/manage-data/table-storage-usage) |

## External tables

External tables have the most developed troubleshooting material in the docs — [External table troubleshooting](/corecapabilities/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](/corecapabilities/external-table/troubleshooting) |
| Operational problems, including ZooKeeper packet-size overflow as segment count grows | [Operational guidance → Additional troubleshooting](/corecapabilities/external-table/operational-guidance#additional-troubleshooting) |
| General questions and behaviour | [External tables FAQ](/corecapabilities/external-table/faq) |
| Monitoring sync state, lag and freshness | [External table observability](/corecapabilities/external-table/observability) |
| A type not mapping as you expect | [Data type mapping → Known limitations](/corecapabilities/external-table/data-type-mapping#known-limitations) |
| Deletion vector or segment group behaviour | [Deletion vectors → FAQs](/corecapabilities/external-table/deletion-vectors#faqs) · [Large External Tables → FAQs](/corecapabilities/external-table/segment-groups#faqs) |
| Catalog-specific constraints | The `Limitations` section on your catalog's onboarding page — [Glue](/corecapabilities/external-table/glue/onboarding-api#limitations) · [Unity](/corecapabilities/external-table/unity/onboarding-api#limitations) · [Polaris](/corecapabilities/external-table/polaris/onboarding-api#limitations) · [Nessie](/corecapabilities/external-table/nessie/onboarding-api#limitations) · [S3](/corecapabilities/external-table/s3/onboarding-api#limitations) · [S3 Tables](/corecapabilities/external-table/s3tables/onboarding-api#limitations) · [GCS](/corecapabilities/external-table/gcs/onboarding-api#limitations) |

## Security and access

| If you are dealing with | Go to |
| - | - |
| Audit logs not appearing or not containing what you expect | [Pinot audit logs → Troubleshooting](/corecapabilities/security/audit/pinot-audit-logs#troubleshooting) |
| Row-level policies not filtering as intended | [Row-level access control → Limitations](/corecapabilities/security/row-level-access-control#limitations) |
| Working out which action governs an operation | [RBAC actions](/corecapabilities/security/actions) |

## Interfaces and integrations

| If you are dealing with | Go to |
| - | - |
| Elasticsearch-compatible queries | [Elasticsearch gateway → Troubleshooting](/corecapabilities/query_data/query_interfaces/elasticsearch-gateway#troubleshooting) and its [Limitations](/corecapabilities/query_data/query_interfaces/elasticsearch-gateway#limitations) |
| Semantic search behaviour | [Semantic search → Troubleshooting](/corecapabilities/ai/semantic-search#troubleshooting) |
| The MCP server | [StarTree MCP → Limitations](/corecapabilities/query_data/mcp/startree-mcp#limitations) |
| Generative AI recipes | [GenAI recipe → Troubleshooting](/recipes/genai#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](/corecapabilities/cluster-operations/scheduled-server-scaling#troubleshooting) and its [Notes and limitations](/corecapabilities/cluster-operations/scheduled-server-scaling#notes-and-limitations) |
| Cluster-, broker-, controller- or minion-level health checks | [Health checks: instance-level](/corecapabilities/observability/health-checks#instance-level-checks) and [cluster-level](/corecapabilities/observability/health-checks#cluster-level-checks) |
| A specific table health check failing, and what its diagnostic fields mean | [Health check reference](/corecapabilities/observability/health-checks) |
| Finding the log line behind a symptom | [Accessing logs](/corecapabilities/observability/access-logs) |
| A table whose storage footprint is growing | [Storage efficiency](/corecapabilities/manage-data/storage-efficiency) and [Table Storage Usage](/corecapabilities/manage-data/table-storage-usage) |

## ThirdEye

ThirdEye has its own troubleshooting section under its own tab:

* [ThirdEye FAQ](/thirdeye/troubleshooting/faq)
* [ThirdEye observability and monitoring](/thirdeye/troubleshooting/thirdeye-observability-and-monitoring)
* [Getting help with ThirdEye](/thirdeye/troubleshooting/get-help)

<Tip>
  Not finding what you need here? Work through the [symptom guides](/corecapabilities/observability/troubleshooting) 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.
</Tip>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.