docs: improve SSL certificate troubleshooting guidance

fahe1em1 · fahe1em1 · commit 0c3792e81973 · 2026-03-12T19:27:19.000Z
diff --git a/docs/faqs.mdx b/docs/faqs.mdx
@@ -38,7 +38,15 @@ If you're seeing a `fetch failed` error and your network requires custom certifi
 
 You may also set `requestOptions.caBundlePath` to an array of paths to multiple certificates.
 
-**_Windows VS Code Users_**: Installing the [win-ca](https://marketplace.visualstudio.com/items?itemName=ukoloff.win-ca) extension should also correct this issue.
+**_Windows VS Code Users_**: Installing the [win-ca](https://marketplace.visualstudio.com/items?itemName=ukoloff.win-ca) extension may help Continue use the Windows certificate store, but `requestOptions.caBundlePath` is the most reliable fix.
+
+### Common SSL certificate errors
+
+If your logs include errors such as `unable to verify the first certificate`, `self signed certificate in certificate chain`, `certificate verify failed`, or `CERT_UNTRUSTED`, Continue was able to reach the endpoint but could not verify the TLS certificate chain it returned.
+
+In most cases, the fix is to export the root or intermediate CA certificate for that endpoint and set `requestOptions.caBundlePath` in your model configuration. If the server also requires mutual TLS, add `requestOptions.clientCertificate` as well.
+
+For step-by-step diagnosis with `curl` and `openssl`, see [Troubleshooting SSL certificate errors](/troubleshooting#ssl-certificate-errors).
 
 ### VS Code Proxy Settings
 
@@ -382,4 +390,4 @@ If you'd like to perform a clean reset of the extension, including removing all
 
 ## Still having trouble?
 
-You can also join [GitHub Discussions](https://github.com/continuedev/continue/discussions) for additional support. Alternatively, you can create a GitHub issue [here](https://github.com/continuedev/continue/issues/new?assignees=&labels=bug&projects=&template=bug-report-%F0%9F%90%9B.md&title=), providing details of your problem, and we'll be able to help you out more quickly.
+You can also join [GitHub Discussions](https://github.com/continuedev/continue/discussions) for additional support. Alternatively, you can create a GitHub issue [here](https://github.com/continuedev/continue/issues/new?assignees=&labels=bug&projects=&template=bug-report-%F0%9F%90%9B.md&title=), providing details of your problem, and we'll be able to help you out more quickly.
diff --git a/docs/guides/how-to-self-host-a-model.mdx b/docs/guides/how-to-self-host-a-model.mdx
@@ -120,3 +120,5 @@ config.json
   ]
 }
 ```
+
+If your endpoint uses a private or corporate CA but does not require mutual TLS, configure `requestOptions.caBundlePath` instead. For common errors like `unable to verify the first certificate` or `CERT_UNTRUSTED`, see [Configure Certificates](/faqs#configure-certificates) and [SSL certificate errors](/troubleshooting#ssl-certificate-errors).
diff --git a/docs/troubleshooting.mdx b/docs/troubleshooting.mdx
@@ -8,7 +8,8 @@ description: "Comprehensive guide to resolving common issues with Continue, incl
 3. [Download an older version](#download-an-older-version)
 4. [Resolve keyboard shortcut issues](#keyboard-shortcuts-not-resolving)
 5. [MCP Server connection issues](#mcp-server-connection-issues)
-6. [Check FAQs for common issues](/faqs)
+6. [SSL certificate errors](#ssl-certificate-errors)
+7. [Check FAQs for common issues](/faqs)
 
 ## Check the logs
 
@@ -104,6 +105,65 @@ To find the full path to a command on your system:
 
 This issue typically affects macOS users with large development environments and is being tracked in [#7870](https://github.com/continuedev/continue/issues/7870) and [#6699](https://github.com/continuedev/continue/issues/6699).
 
+## SSL certificate errors
+
+If Continue can reach your model endpoint but cannot verify its TLS certificate chain, you may see `fetch failed` alongside errors such as:
+
+- `unable to verify the first certificate`
+- `self signed certificate in certificate chain`
+- `certificate verify failed`
+- `CERT_UNTRUSTED`
+
+This usually happens when you are connecting to a self-hosted model, enterprise proxy, or internal endpoint that uses a private CA or an incomplete certificate chain.
+
+### Quick fix: trust the CA bundle
+
+Add the root or intermediate certificate for that endpoint to your model's `requestOptions.caBundlePath`:
+
+```yaml
+models:
+  - name: Secure endpoint
+    provider: openai
+    model: gpt-4.1
+    apiBase: https://llm.example.com/v1
+    requestOptions:
+      caBundlePath: /path/to/ca-chain.pem
+```
+
+If your setup requires mutual TLS, configure `requestOptions.clientCertificate` too. The self-hosting guide includes an example in [How to Set Up Authentication](/guides/how-to-self-host-a-model#how-to-set-up-authentication).
+
+### Diagnose the certificate problem
+
+1. Reproduce the error in the Continue logs so you can confirm the exact hostname that failed.
+2. Test the endpoint directly with `curl`:
+
+   ```bash
+   curl -v https://llm.example.com/v1/models
+   ```
+
+3. Inspect the certificate chain with OpenSSL:
+
+   ```bash
+   openssl s_client -showcerts -connect llm.example.com:443 -servername llm.example.com </dev/null
+   ```
+
+4. Save the required root or intermediate certificate as a PEM file and point `requestOptions.caBundlePath` at it.
+5. Verify the fix with curl before retrying in Continue:
+
+   ```bash
+   curl --cacert /path/to/ca-chain.pem https://llm.example.com/v1/models
+   ```
+
+### Common setups
+
+For self-hosted or enterprise deployments, these options usually help:
+
+- Private CA or corporate proxy: set `requestOptions.caBundlePath`
+- Mutual TLS: set `requestOptions.clientCertificate`
+- Windows VS Code: if your certificates are managed through the Windows certificate store, the [win-ca extension](https://marketplace.visualstudio.com/items?itemName=ukoloff.win-ca) may help, but `requestOptions.caBundlePath` remains the most reliable option
+
+As a temporary debugging step, you can set `requestOptions.verifySsl: false` to confirm the failure is certificate-related. Do not leave this disabled in normal use.
+
 
 ## Still having trouble?
 

Original file line number	Diff line number	Diff line change
`@@ -120,3 +120,5 @@ config.json`
`120`	`120`	`]`
`121`	`121`	`}`
`122`	`122`	```
	`123`	`+`
	`124`	+If your endpoint uses a private or corporate CA but does not require mutual TLS, configure `requestOptions.caBundlePath` instead. For common errors like `unable to verify the first certificate` or `CERT_UNTRUSTED`, see [Configure Certificates](/faqs#configure-certificates) and [SSL certificate errors](/troubleshooting#ssl-certificate-errors).