> ## Documentation Index
> Fetch the complete documentation index at: https://docs.open-cluster.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Resolve startup, readiness, integration, Relay, and investigation failures.

Start with the exact error shown by OpenCluster. Startup and verification errors name
the configuration or remote access that failed.

## Process and database

| Symptom                                       | Check                                                                                                                   |
| --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| Startup exits with an `OC_` variable          | Correct the named value or missing paired setting. OpenCluster does not start with invalid configuration.               |
| `/healthz` is `200`, `/readyz` is `503`       | Check the PostgreSQL placement, DSN file, network path, and database health. Restarting does not repair the dependency. |
| Slack cannot be enabled without a sealing key | Configure a 32-byte `OC_SEALING_KEY_FILE` and restart.                                                                  |

## Integrations

| Symptom                                   | Check                                                                               |
| ----------------------------------------- | ----------------------------------------------------------------------------------- |
| Alertmanager returns `401`                | Replace the webhook secret, or enable the integration.                              |
| Alertmanager verification has no delivery | Check its route, receiver URL, custom header, and network access to intake.         |
| Slack returns `invalid_auth`              | Paste a current token and verify it again.                                          |
| Slack history is empty                    | Invite the app to the public channel and grant `channels:history`.                  |
| GitHub installation is unknown            | Confirm the installation ID belongs to the configured App and the App is installed. |
| A credential cannot be opened             | The sealing key changed. Paste the integration credential again.                    |
| Delete is refused                         | Retained operational records depend on the integration. Disable it instead.         |

## Relays and Kubernetes

| Symptom                                    | Check                                                                                                       |
| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------- |
| Relay is not connected                     | Check Relay logs, endpoint, TLS pin, and outbound network path.                                             |
| Kubernetes verification lacks capabilities | Check the Relay version and its Kubernetes RBAC.                                                            |
| Workload inventory is missing              | Check the namespace allow-list, service-account access, inventory interval, and when synchronization began. |

## Investigations

| Symptom                                  | Check                                                                                                |
| ---------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| No model provider is configured          | Set the provider, model, key file, and consent list.                                                 |
| Configured provider is not consented     | Add the same provider to `OC_MODEL_CONSENTED_PROVIDERS`.                                             |
| Investigation capacity is full           | Wait for a running investigation to finish, then retry.                                              |
| Investigation failed                     | Read the recorded reason. Check provider credentials, endpoint, limits, and provider status.         |
| Investigation concluded with no findings | Review the reads and connect the missing source; the available data supported no defensible finding. |
| A read is truncated                      | Narrow the question, repository, channel, or time window where possible.                             |

Use [Understand findings and citations](/investigations/findings-and-citations) to
interpret partial and empty conclusions.