Troubleshooting

Connection Issues

Connection Timeout

Error: Connection timed out or ETIMEDOUT

Causes:

• Server is slow to respond
• Network connectivity issues
• Firewall blocking the connection
• Incorrect port number

Solutions:

1. Increase timeout setting:
   JSON

   {
     "sslens.timeout": 30000
   }

2. Check if you can access the domain in your browser
3. Verify the port number (default is 443)
4. Check if a proxy or VPN is interfering

Connection Refused

Error: ECONNREFUSED

Causes:

• No service running on the specified port
• Server is down
• Wrong port number

Solutions:

1. Verify the server is running
2. Check if the port is correct (try port 443 if unsure)
3. For local servers, ensure they're started

DNS Resolution Failed

Error: ENOTFOUND or getaddrinfo ENOTFOUND

Causes:

• Domain name misspelled
• Domain doesn't exist
• DNS server issues

Solutions:

1. Double-check the domain spelling
2. Try using an IP address instead of hostname
3. Check your DNS settings
4. Try: nslookup domain.com in terminal to verify DNS

Proxy/VPN Issues

If you're behind a corporate proxy or using a VPN:

Workarounds:

• Temporarily disable the proxy/VPN if possible
• Add exceptions for the domains you need to inspect
• Use the domain's IP address directly

Certificate Issues

Self-Signed Certificate

Message: "Self-signed certificate" or SELF_SIGNED_CERT_IN_CHAIN

This is not an error - SSLens can still inspect self-signed certificates. You'll see a warning indicator, but all certificate details will be displayed.

Expired Certificate

Message: "Certificate has expired" or CERT_HAS_EXPIRED

SSLens can still inspect expired certificates. The certificate panel will show the expiration status with a red indicator (🔴).

Certificate Chain Incomplete

Message: "Unable to verify certificate chain" or missing intermediate certificates

Causes:

• Server not sending intermediate certificates
• Misconfigured SSL on the server

What you can do:

• SSLens will show whatever certificates are available
• The chain validation feature will report the issue
• For your own servers: ensure intermediate certificates are properly configured

Hostname Mismatch

Error: ERR_TLS_CERT_ALTNAME_INVALID

The hostname you're connecting to doesn't match any name in the certificate's Subject Alternative Names (SANs).

Solutions:

• Use the exact hostname that appears in the certificate
• Check the certificate's SANs field to see valid hostnames

Extension Issues

Extension Not Activating

If SSLens commands don't appear in the Command Palette:

1. Reload VS Code: Cmd+Shift+P → "Developer: Reload Window"
2. Check if the extension is installed and enabled in Extensions view
3. Check the VS Code version (SSLens requires 1.85.0+)

Sidebar Not Visible

If the SSLens icon (🛡️) doesn't appear in the Activity Bar:

1. Right-click the Activity Bar and ensure "SSLens" is checked
2. Reload VS Code
3. Reinstall the extension

Panel Not Opening

If the certificate panel doesn't appear after fetching:

1. Check the Output panel for errors (View → Output → Select "SSLens")
2. Try fetching a known-working domain like github.com
3. Reload VS Code

Settings Not Saving

If saved domains or settings are lost:

1. Ensure you have write permissions to VS Code's user settings
2. Check if Settings Sync is causing conflicts
3. Try saving settings to workspace instead of user settings

SSL Pinning Issues

Generated Code Not Working

If the generated pinning code causes connection failures:

1. Verify the hash is correct: Fetch the certificate again and compare hashes
2. Check for certificate rotation: The server may have a new certificate
3. Include backup pins: Always have at least one backup pin
4. Pin the intermediate CA: More stable than pinning leaf certificates

App Locked Out After Certificate Change

If your app can't connect after a certificate change:

Solutions:

1. Release an app update with the new certificate pins
2. Consider pinning to the intermediate CA instead (more stable)
3. Implement a pin expiration strategy (Android Network Security Config)

Hash Format Wrong

Different platforms expect different hash formats:

Frequently Asked Questions

Can SSLens inspect certificates behind authentication?

SSLens only performs the TLS handshake to retrieve certificates. It doesn't send HTTP requests or handle authentication. The certificate is obtained before any HTTP-level authentication occurs, so you can inspect certificates even for authenticated endpoints.

Does SSLens work with client certificates (mTLS)?

Currently, SSLens doesn't support providing client certificates for mutual TLS authentication. It works as a standard TLS client without client certificate authentication.

Can I inspect certificates from internal/private domains?

Yes, as long as your machine can resolve and connect to the domain. SSLens works with:

• Internal company domains
• Self-signed certificates
• Private CA-signed certificates
• Localhost with TLS

Why does the public key hash differ from online tools?

Different tools may calculate hashes differently:

• Some hash the entire certificate, others hash just the public key
• SPKI includes algorithm info, raw public key hash doesn't
• Some tools use different hash algorithms (SHA-1 vs SHA-256)

SSLens uses the standard SHA-256 hash of the public key, Base64 encoded, which is compatible with most pinning implementations.

Is my data sent anywhere?

No. SSLens operates entirely locally. It:

• Only connects directly to the domains you specify
• Stores all data locally in VS Code settings
• Never sends data to SSLens servers (there are none)
• Is fully open source for verification

Can I use SSLens offline?

SSLens requires network access to fetch certificates from remote domains. However, you can:

• Inspect local certificate files (.pem, .crt, .der) offline
• View previously fetched certificates from the sidebar

Get Help

Debug Information

When reporting issues, include:

1. VS Code version (Help → About)
2. SSLens version (Extensions panel)
3. Operating system
4. Error message (from Output panel: View → Output → SSLens)
5. Domain you're trying to inspect (if not sensitive)

Report an Issue

If you've tried the solutions above and still have problems: