> 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/catalogs/troubleshooting-catalogs.md).

# Troubleshooting catalogs

Resolve common catalog connection, cross-account, and refresh failures in e6data.

When a catalog operation fails, the catalog row shows an **Error** status with a brief reason. Use the **Retry** icon for transient failures, **Download log** to capture details for support, and **Refresh List** to update statuses without re-fetching metadata. For specific error codes, see [Catalog errors](/query-engine/reference/error-codes/catalog.md).

## Connection failures

| Symptom                           | Likely cause                             | Fix                                                                                   |
| --------------------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------- |
| Test Connection fails immediately | Wrong host/port or unreachable metastore | Verify the connection details and that the metastore is reachable from your workspace |
| Authentication rejected           | Bad credentials or expired token         | Re-check credentials; for Unity/Databricks, confirm the access token hasn't expired   |
| Network/firewall block            | Metastore port not open to e6data        | Allow the metastore port (for example, Hive Thrift `9083`) through firewalls and NSGs |
| Insufficient permissions          | The identity can't list schemas          | Grant the identity read access to the metastore and underlying storage                |

## Cross-account access

| Symptom                      | Likely cause                                     | Fix                                                                                                               |
| ---------------------------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
| Role cannot be assumed (AWS) | Trust policy missing e6data's principal          | Confirm the trust policy names the correct e6data account/role and includes `sts:AssumeRole` and `sts:TagSession` |
| Access denied to storage     | The cross-account role lacks storage read        | Grant read on the S3 bucket / ADLS Gen2 account                                                                   |
| Wrong account/tenant values  | Mismatched Target Account ID or Tenant/Client ID | Re-enter the cross-account values; for Azure, verify Tenant ID, Client ID, and Storage Account Name               |

See [Cross-account access](/query-engine/guides/catalogs/cross-account.md) for the full patterns.

## Schema and refresh issues

| Symptom                                 | Likely cause                                 | Fix                                                                                                                                                |
| --------------------------------------- | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| Tables missing after a metastore change | Catalog metadata is stale                    | Refresh the affected schemas - see [Register and manage catalogs](/query-engine/guides/catalogs/register-and-manage-catalogs.md#refresh-a-catalog) |
| Scheduled refresh shows **Failed**      | Credentials expired or metastore unreachable | Check the refresh logs; the catalog keeps its previous metadata until the next successful run                                                      |
| Schema list empty after Test Connection | The identity can't see any databases         | Verify the identity's grants on the metastore                                                                                                      |

## See also

* [Register and manage catalogs](/query-engine/guides/catalogs/register-and-manage-catalogs.md)
* [Cross-account access](/query-engine/guides/catalogs/cross-account.md)
* [Catalog errors](/query-engine/reference/error-codes/catalog.md)


---

# 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/catalogs/troubleshooting-catalogs.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.