---
url: 'https://docs.smoxy.eu/ssl-and-certificates/ssl-troubleshooting.md'
---
# SSL Troubleshooting

This guide covers common SSL issues in smoxy and how to resolve them.

***

### Understanding SSL Status

Your certificate's status and each SAN's DNS status are visible on the **SSL Certificates** page - open a certificate to see its **SANs** tab. The following conditions indicate an issue:

#### Pending

**Meaning:** Certificate generation has been initiated but is not yet complete.

**What to do:**

* Verify that all `_acme-challenge` CNAME records are configured at your DNS provider
* Allow time for DNS propagation (typically a few minutes, but can take up to 48 hours)
* smoxy will automatically pick up the generation once DNS is verified

**If stuck for more than 1 hour:**

* Check each SAN's DNS status on the certificate's SANs tab
* Look for SANs with "Missing" DNS status and fix those records
* smoxy retries automatically with increasing intervals

#### DNS Status: Missing

**Meaning:** The required `_acme-challenge` CNAME record was not found for one or more SANs. A record that points to the wrong target, or a conflicting TXT record, both also result in a `Missing` status - see the causes below.

**Resolution:**

1. Check the expected CNAME record shown on the certificate's SANs tab
2. Add the record at your DNS provider:

   ```
   Type:   CNAME
   Name:   _acme-challenge
   Target: yourdomain.com.acme.smoxy.eu.  (use the exact value shown on the SANs tab)
   ```
3. Wait for DNS propagation
4. smoxy checks missing records every **1 hour** and will detect the change automatically

#### Cause: CNAME points to the wrong target

**Meaning:** A CNAME record for `_acme-challenge` exists, but it points to the wrong target, so the SAN stays in the `Missing` DNS status.

**Resolution:**

1. Go to your DNS provider
2. Update the `_acme-challenge` CNAME to the exact target shown on the certificate's SANs tab
3. smoxy will verify the updated record on the next check

#### Cause: conflicting TXT record

**Meaning:** A TXT record for `_acme-challenge` exists, which conflicts with the required CNAME record and keeps the SAN in the `Missing` DNS status.

**Why this happens:** Some DNS providers or previous setups may have created a TXT record for ACME challenges. smoxy requires a CNAME record instead.

**Resolution:**

1. Remove the TXT record for `_acme-challenge` at your DNS provider
2. Ensure only the CNAME record exists
3. smoxy will detect the change on the next check

***

### Common Scenarios

#### Cloudflare Users

If you use Cloudflare as your DNS provider:

1. **Disable the Cloudflare proxy** (orange cloud) for the `_acme-challenge` CNAME record
2. The record must be **DNS Only** (grey cloud) for ACME verification to work
3. Your regular traffic records can still use the Cloudflare proxy

See [Cloudflare Setup](/developer-guide/cloudflare-setup) for detailed instructions.

#### Certificate Not Renewing Automatically

Auto-generated certificates renew within the CA's recommended renewal window (roughly two weeks before expiry as a fallback). If renewal isn't happening:

1. **Check DNS records** - The `_acme-challenge` CNAME records must still be in place
2. **Check SAN DNS status** - Open the certificate's SANs tab and verify all SANs show `Valid` DNS status
3. **Rate limits** - If smoxy hit Let's Encrypt rate limits, it waits before retrying

::: info
**Note:** Self-managed certificates are **never** auto-renewed. You must upload a replacement yourself.
:::

#### Multiple Subdomains Not Covered

The default wildcard (`*.yourdomain.com`) covers single-level subdomains. It does **not** cover:

* Multi-level subdomains like `sub.shop.yourdomain.com`
* Different top-level domains

For these cases, smoxy can add additional SANs. Each additional SAN requires its own `_acme-challenge` CNAME record.

#### Certificate Shows as Expired

If your certificate has expired:

* **Auto-managed:** Check if the `_acme-challenge` DNS records are still in place. If they are, smoxy will attempt to renew. If they were removed, add them back.
* **Self-managed:** Upload a new certificate. smoxy cannot renew certificates it didn't generate.

#### SSL Generation Fails Repeatedly

If you see repeated failures in the SSL generation process:

| Error                       | Cause                                                              | Resolution                                          |
| --------------------------- | ------------------------------------------------------------------ | --------------------------------------------------- |
| **CNAME record missing**    | The `_acme-challenge` CNAME record is missing for one or more SANs | Add the required CNAME record(s)                    |
| **CNAME record invalid**    | The CNAME record exists but points to the wrong target             | Update it to the exact target shown on the SANs tab |
| **DNS provisioning failed** | smoxy could not create the DNS-01 challenge record                 | Temporary - smoxy retries automatically             |
| **ACME error**              | The certificate authority reported an error                        | Check DNS propagation; smoxy retries automatically  |
| **Rate limit**              | Too many certificate requests to Let's Encrypt                     | Automatic - smoxy waits and retries later           |
| **Internal error**          | An unexpected error occurred                                       | smoxy retries; contact support if it persists       |

smoxy uses **exponential backoff** when retrying, increasing the wait time between attempts to avoid overwhelming external services.

***

### Certificate Verification

To independently verify your SSL certificate is working:

#### Using a Browser

1. Visit your domain with `https://`
2. Click the padlock icon in the address bar
3. View certificate details to confirm:
   * Issued to the correct domain
   * Valid date range
   * Issued by the expected CA (Let's Encrypt for auto-managed)

#### Using Command Line

```bash
# Check certificate details
openssl s_client -connect yourdomain.com:443 -servername yourdomain.com < /dev/null 2>/dev/null | openssl x509 -text -noout

# Check certificate expiration
echo | openssl s_client -connect yourdomain.com:443 -servername yourdomain.com 2>/dev/null | openssl x509 -noout -dates
```

***

### Getting Help

If you've followed the troubleshooting steps and your SSL issue persists:

1. Note the exact status messages shown in smoxy
2. Check the **Activity Log** (under Team settings) for SSL-related events
3. Contact smoxy support with your domain name and the error details