# Troubleshooting

Pick the area closest to what is failing. Every guide below lives beside the feature it covers, so none of this is a second copy that drifts from the first.

## Connecting

|                                                     |                                                                                                                  |
| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| A connection is refused                             | [Connection Denied](https://docs.shellhub.io/manage/access-control/connection-denied)                            |
| A login hangs instead of refusing                   | [Login Approvals](https://docs.shellhub.io/manage/access-control/login-approvals) — a key waiting to be approved |
| Sessions from a legacy namespace behave differently | [Upgrading a Legacy Namespace](https://docs.shellhub.io/manage/access-control/migrating-from-legacy)             |

## Devices

|                                        |                                                                                                                          |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| A device never showed up               | [Device Not Appearing](https://docs.shellhub.io/manage/devices/device-not-appearing)                                     |
| It arrived pending instead of accepted | [Provisioning Keys](https://docs.shellhub.io/manage/devices/provisioning-keys) — the key’s mode decides                  |
| A device came back that you deleted    | [Device Not Appearing](https://docs.shellhub.io/manage/devices/device-not-appearing#did-an-old-device-come-back-instead) |

## Signing in

|                              |                                                                                                      |
| ---------------------------- | ---------------------------------------------------------------------------------------------------- |
| SAML fails                   | [SAML Sign-In Fails](https://docs.shellhub.io/manage/team/sso-not-working) — check the license first |
| Somebody cannot see a device | [User Roles](https://docs.shellhub.io/manage/team/user-roles)                                        |

## Your own server

|                                                       |                                                                        |
| ----------------------------------------------------- | ---------------------------------------------------------------------- |
| The stack will not come up, or a service is unhealthy | [Troubleshooting](https://docs.shellhub.io/selfhosted/troubleshooting) |
| Certificates, the database, the gateway               | [Troubleshooting](https://docs.shellhub.io/selfhosted/troubleshooting) |
| It broke after an upgrade                             | [Upgrade](https://docs.shellhub.io/selfhosted/upgrade)                 |

## Automation

|                                         |                                                                                                     |
| --------------------------------------- | --------------------------------------------------------------------------------------------------- |
| A playbook or pipeline hangs at connect | The API key has no SSH key enrolled yet. [SSH Access](https://docs.shellhub.io/api/ssh-access)      |
| A generated client returns 404          | The spec was the wrong edition. [the specification](https://docs.shellhub.io/api#the-specification) |

## Still stuck

[Getting Support](https://docs.shellhub.io/help/support) has where to ask, what to include so the first answer is useful, and what to redact before pasting.
