> For the complete documentation index, see [llms.txt](https://docs.e6data.com/query-engine/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.e6data.com/query-engine/guides/clusters/troubleshooting-clusters.md).

# Troubleshooting clusters

Common cluster problems - stuck states, timeouts, degraded executors, and connection issues - with fixes.

| Symptom                                    | Likely cause                                       | Fix                                                                                                                                                                        |
| ------------------------------------------ | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Cluster stuck in **Creating**              | Insufficient capacity                              | Wait for resources; contact support if persistent                                                                                                                          |
| Cluster **suspended unexpectedly**         | Auto-suspend idle timeout fired                    | Increase the idle timeout or disable auto-suspend for always-on clusters                                                                                                   |
| **Resume taking > 90 s**                   | Large cluster (XL+) or cold nodes                  | Expected for large sizes; keep min executors > 0 for fast resume                                                                                                           |
| Cluster in **Failed** state                | Startup or configuration error                     | Check the error code in Activity History and follow [Lifecycle states and error codes](/query-engine/guides/clusters/lifecycle-states-and-error-codes.md)                  |
| **Queries timing out**                     | Query timeout too low or cluster under-provisioned | Raise the query timeout or scale up executors                                                                                                                              |
| Cluster **degraded** (some executors down) | Node issues or resource pressure                   | Queries still run, slower; the cluster may self-heal                                                                                                                       |
| **Auto-resume not working**                | Auto-resume disabled, or the workspace is disabled | Verify auto-resume is enabled; check whether the workspace itself is disabled                                                                                              |
| **Version update stuck**                   | New version failing health checks                  | Check the deployment phase; e6data auto-rolls back if the new version is unhealthy - see [Zero-downtime upgrades](/query-engine/guides/clusters/zero-downtime-upgrades.md) |
| **Can't connect** to a running cluster     | Networking, not the cluster                        | Check network configuration and firewall rules - see [Endpoints and cluster ingress](broken://pages/Wh4d9jql2OPH1ux7JE4O)                                                  |

Use **Activity History** on the cluster as the first stop - it records each operation with timestamps and error detail. For the full error-code reference, see [Lifecycle states and error codes](/query-engine/guides/clusters/lifecycle-states-and-error-codes.md).

## See also

* [Lifecycle states and error codes](/query-engine/guides/clusters/lifecycle-states-and-error-codes.md)
* [Create and manage clusters](/query-engine/guides/clusters/create-and-manage-clusters.md)
* [Cluster errors (reference)](/query-engine/reference/error-codes/cluster.md)
* [CloudPrem cluster operations](/query-engine/guides/clusters/cloudprem-cluster-operations.md) - for In-VPC kubectl diagnostics.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.e6data.com/query-engine/guides/clusters/troubleshooting-clusters.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.