# Troubleshooting common issues

Source: https://www.storeframe.io/docs/help/troubleshooting

Self-serve answers for the most common StoreFrame issues — start here before filing a ticket.

Hit something that didn't work? Start here. Most issues fall into one of four buckets:

| Issue                                                         | Go to                                                                              |
| ------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| Environment is stuck in "Provisioning failed" or "Failed"     | [Provisioning failed](/docs/help/troubleshooting/provisioning-failed)              |
| Cannot connect via SSH                                        | [SSH cannot connect](/docs/help/troubleshooting/ssh-cannot-connect)                |
| Visitors or integrations get 403, 429 or a browser check page | [Blocked, challenged or rate limited](/docs/help/troubleshooting/blocked-requests) |
| Custom domain not resolving, or SSL certificate pending       | [DNS and domains](/docs/help/troubleshooting/dns-and-domains)                      |
| You saw an error message and want to know what it means       | [Common errors](/docs/help/troubleshooting/common-errors)                          |

![Troubleshooting chapter overview](https://www.storeframe.io/assets/docs/help/troubleshooting/troubleshooting-chapter-overview.png)

## Before you file a ticket

Work through this checklist first. It resolves most issues without a support round-trip and gives the support team the context they need if it doesn't.

**1. Check the status page.**
If provisioning or Hub access is failing for everyone, there may be an active incident. Visit the [status page](/docs/help/support/status) before troubleshooting locally.

**2. Refresh the environment detail page.**
The Hub syncs environment state via WebSocket. If you were looking at a stale tab during a transition (provisioning → active), a hard refresh is enough.

**3. Check the environment's current lifecycle status.**
Open the environment and look at the status badge. "Failed" and "Provisioning" mean different things — the [provisioning-failed](/docs/help/troubleshooting/provisioning-failed) page explains each.

**4. Wait the expected propagation window.**

* SSH keys: up to 1 minute after adding
* DNS records: up to 48 hours depending on your registrar TTL (usually much less)
* SSL certificates: up to 2 minutes after DNS propagates

**5. Re-read the exact error message.**
The [common errors](/docs/help/troubleshooting/common-errors) reference lists the most frequent messages with their causes and fixes. Copy the exact text into the search bar.

**6. Reproduce with a clean state.**
Clear local SSH agent identity, use a fresh terminal, and retry the operation once. Intermittent failures can mask the real cause.

**7. Gather context before filing.**
If none of the above resolves it, [file a support ticket](/docs/help/support/file-a-ticket) and include:

* The environment ID (visible in the URL: `/environment/[id]`)
* The exact error message or error code
* What you were doing when it happened
* Approximate UTC time (helps correlate with logs)

The more context you provide, the faster resolution tends to be.
