> ## Documentation Index
> Fetch the complete documentation index at: https://docs.incident.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Troubleshooting
> Diagnose a data source that's failing, returning nothing, or asking to be reconnected.
Every data source has a detail page in your [telemetry settings](https://app.incident.io/~/nexus/telemetry) that shows how it's doing: its connection health, its query results, and why queries failed. This page covers what you'll see there and how to fix each problem.
## Connection health
Each data source carries a connection status from its most recent check:
* **Connected**: the last check passed. Nothing to do.
* **Degraded**: the source is usable and Nexus keeps querying it, but something non-blocking is off, most commonly that the source holds no recent data. Check the detail on the data source's page to see what.
* **Connection failed**: the last check found a blocking problem, so the source can't currently be reached or used. Run the connection test to see which requirement failed.
## When a data source needs reconnecting
When a data source stops being usable, its page shows a banner and Nexus pauses queries against it until you act. This happens for three reasons:
* **Authentication failures**: the provider repeatedly rejected the credentials, so Nexus stopped querying the source and flagged it. Reconnect with fresh credentials to restore access.
* **Missing permissions**: the credentials still authenticate, but a permission Nexus needs has been revoked. Grant the missing permission to the existing credential; reconnecting with the same key changes nothing.
* **Configuration required**: the source is missing something it was never given, such as a database discovered through a provider that has no credentials yet, or a private resource Nexus can't reach without a [proxy](/integrations/proxy). Finish the setup from the data source's page.
## Testing the connection
Select **Test connection** on a data source's page to run a fresh check. It works through each requirement in turn: reaching the endpoint, authenticating, permissions, access to the data. When one fails, it names exactly what's missing and how to fix it, down to the specific permission to grant.
## Failed queries
The detail page also breaks failed queries down by category, so when a source has a low query success rate you can see *why*. Most categories are about the data source itself; a couple are things you can fix directly.
| Category | What it means | What to do |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| **Rate limited** | The provider rate-limited our queries. | Usually eases on its own. If it persists, raise the provider's API rate limits or quota where possible. |
| **Timeout** | The query ran longer than our time limit and was cut off. | Eases as Nexus learns to write faster queries. Scaling and improving performance of the data source can also help where possible. |
| **Provider error** | The provider's own backend returned an error (a 5xx). The query itself was valid. | Usually transient. Check the provider's status if it keeps happening. |
| **Unauthorized** | The provider rejected our credentials. | Reconnect the data source to refresh its credentials. |
| **Invalid query** | The query we built wasn't valid for this source, such as an unknown field, a filter that matched nothing, or a time range outside the source's retention. | Improves automatically as Nexus learns your stack. Contact support if it stays high. |
| **Unknown** | A failure we couldn't categorize. | Contact support if you see a sustained run of these. |
A healthy source occasionally errors, that's normal. It's a sustained shift in one category that's worth acting on,
like a jump in **Unauthorized** (reconnect) or **Rate limited** (provider limits).
## Queries succeed but return nothing
The detail page separates queries that returned data from ones that came back empty, so a source that always returns nothing stands out even when every query succeeds. The common causes:
* **The connection is scoped to the wrong place**: an index pattern, dataset, or project that doesn't hold the data your team asks about. Check the data source's configuration.
* **The data has aged out**: queries target a window the source no longer holds. Check the retention settings below.
* **The source genuinely doesn't hold that data**: enable the sources your responders reach for during incidents instead.
## Retention windows
Nexus queries within a data source's retention window, and a query whose time range falls outside it fails as an invalid query. Nexus learns retention where the data source reports it, and you can set it yourself under **Data source retention** in the data source's settings. If a source's retention has changed (say you shortened it to cut costs), update it there so Nexus stops reaching for data that's gone.
## Related
What you can connect, and how providers and capabilities fit together.
Routing, query planning, guidance, and memory.