SSL/TLS Issues

Troubleshooting certificate and HTTPS problems.

Solutions to common SSL/TLS certificate problems with Supascale.

Start with the preflight check

Before diagnosing anything manually, open the certificate screen for the project. Supascale inspects the server first and reports what will and will not work — whether a reverse proxy such as Coolify or Traefik is holding port 80, whether the domain is proxied through Cloudflare, and which validation method it recommends. Most of the failures below are now caught there rather than after a failed attempt.

"certbot: command not found"

Certbot is installed during setup on every server as of this release. On installs created earlier it was skipped on hosts without a Supascale-managed web server, such as Coolify hosts.

Install it manually:

# Ubuntu/Debian
sudo apt update && sudo apt install -y certbot

# RHEL/Fedora
sudo dnf install -y certbot

Let's Encrypt Issues

HTTP-01 Challenge Failed

Error:

{
  "success": false,
  "error": "Challenge verification failed"
}

Common Causes and Solutions:

Domain not pointing to server:

# Check DNS
dig +short your-domain.com
nslookup your-domain.com

# Should return your server's IP

Port 80 blocked:

# Check if port 80 is open
sudo ufw status
sudo ufw allow 80

# Check firewall/security group
curl http://your-domain.com/.well-known/acme-challenge/test

Reverse proxy not configured:
Nginx must pass through ACME challenges:
```
location /.well-known/acme-challenge/ {
    root /var/www/html;
}
```

DNS propagation not complete:

# Wait for propagation (can take up to 48 hours)
# Check with external DNS
dig @8.8.8.8 your-domain.com

DNS-01 Challenge Failed

Error:

{
  "success": false,
  "error": "DNS record not found"
}

Solutions:

Create correct TXT record:
- Record name: _acme-challenge.your-domain.com
- Record type: TXT
- Value: Provided by Supascale during challenge

Check TXT record:

dig +short TXT _acme-challenge.your-domain.com

Wait for propagation: DNS changes can take 5-30 minutes depending on TTL.
Lower TTL before challenge: Set TTL to 60-300 seconds before requesting certificate.

Rate Limited

Error:

{
  "success": false,
  "error": "Too many certificates requested"
}

Let's Encrypt Rate Limits:

50 certificates per domain per week
5 duplicate certificates per week
5 failed validations per account per hour

Solutions:

Wait for rate limit to reset (1 week for most limits)

Use staging environment for testing:

# Configure Let's Encrypt staging
# Staging has higher limits

Consolidate domains using SAN certificates

Certificate Not Renewing

Problem: Certificate approaching expiration without renewal.

Diagnostic:

# Check certificate expiry
echo | openssl s_client -servername your-domain.com -connect your-domain.com:443 2>/dev/null | openssl x509 -noout -dates

Solutions:

Trigger manual renewal:

POST /api/v1/projects/:id/certificate/renew

Check renewal logs in Supascale system logs
Verify domain still resolves to your server
Check scheduled task is running:
- Go to Scheduled Tasks
- Verify certificate renewal task exists and is enabled

Custom Certificate Issues

Invalid Certificate Format

Error:

{
  "success": false,
  "error": "Invalid certificate format"
}

Solutions:

Ensure PEM format:

# Certificate should start with:
-----BEGIN CERTIFICATE-----

# Private key should start with:
-----BEGIN PRIVATE KEY-----
# or
-----BEGIN RSA PRIVATE KEY-----

Convert from other formats:

# From PFX/PKCS12
openssl pkcs12 -in cert.pfx -out cert.pem -nodes

# From DER
openssl x509 -inform DER -in cert.der -out cert.pem

Remove extra content:
- Remove any text before -----BEGIN
- Remove bag attributes from PFX exports

Certificate Chain Incomplete

Error:

{
  "success": false,
  "error": "Certificate chain incomplete"
}

Solution:

Include full certificate chain in correct order:

-----BEGIN CERTIFICATE-----
(Your server certificate)
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
(Intermediate certificate)
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
(Root certificate - optional)
-----END CERTIFICATE-----

Get intermediate certificates:

# Download from your CA
# Or use openssl to show required chain
openssl s_client -showcerts -connect your-domain.com:443

Private Key Mismatch

Error:

{
  "success": false,
  "error": "Private key does not match certificate"
}

Verify key matches certificate:

# Get certificate modulus
openssl x509 -noout -modulus -in cert.pem | openssl md5

# Get key modulus
openssl rsa -noout -modulus -in key.pem | openssl md5

# MD5 hashes should match

Solution: Generate a new CSR and certificate with matching key, or locate the correct private key.

Certificate Expired

Error:

{
  "success": false,
  "error": "Certificate has expired"
}

Check expiration:

openssl x509 -enddate -noout -in cert.pem

Solution: Upload a valid, non-expired certificate.

Browser SSL Errors

NET::ERR_CERT_AUTHORITY_INVALID

Problem: Browser doesn't trust the certificate.

Causes:

Self-signed certificate
Missing intermediate certificates
Root CA not trusted

Solutions:

Use Let's Encrypt instead of self-signed
Include full certificate chain
Import CA to browser (for internal CAs)

NET::ERR_CERT_COMMON_NAME_INVALID

Problem: Certificate domain doesn't match.

Check certificate domains:

openssl x509 -text -noout -in cert.pem | grep -A1 "Subject Alternative Name"

Solutions:

Ensure certificate covers the domain being accessed
Include www and non-www variants
Request new certificate with correct domains

NET::ERR_CERT_DATE_INVALID

Problem: Certificate dates are invalid.

Check:

openssl x509 -dates -noout -in cert.pem

Causes:

Certificate expired
Certificate not yet valid
Server time incorrect

Solutions:

Renew or replace certificate

Sync server time:

sudo timedatectl set-ntp on
sudo systemctl restart systemd-timesyncd

Reverse Proxy SSL Issues

SSL Termination Configuration

Nginx:

server {
    listen 443 ssl;
    server_name your-domain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    # Modern SSL configuration
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
    ssl_prefer_server_ciphers off;

    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Mixed Content Warnings

Problem: HTTPS page loading HTTP resources.

Solutions:

Set NEXTAUTH_URL to HTTPS:
```
NEXTAUTH_URL=https://your-domain.com
```

Configure proxy headers:

proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Host $host;

Debugging SSL

Test SSL Configuration

# Test connection
openssl s_client -connect your-domain.com:443 -servername your-domain.com

# Check certificate details
echo | openssl s_client -connect your-domain.com:443 2>/dev/null | openssl x509 -text

# Test with curl
curl -vI https://your-domain.com

Online Tools

SSL Labs: https://www.ssllabs.com/ssltest/
Certificate decoder: https://www.sslshopper.com/certificate-decoder.html

Getting Help

When reporting SSL issues, include:

Domain and certificate type (Let's Encrypt or custom)
Error message from Supascale
DNS check results:
```
dig +short your-domain.com
```

SSL test output:

openssl s_client -connect your-domain.com:443 2>&1 | head -20