SSL: Self-signed certificate error when using Claude via Foundation Model APIs in corporate/proxy environments

[smakubi]

Summary

Users on corporate networks with SSL inspection proxies or custom CA certificates encounter a hard-to-diagnose SSL error when the AI Dev Kit attempts to connect to the Claude API via Databricks Foundation Model APIs (FMAPIs). The error manifests as a repeated retry loop with no actionable guidance.

Error Message

Unable to connect to API: Self-signed certificate detected. Check your proxy or corporate SSL certificates
Retrying in 30 seconds… (attempt 8/10)

The process retries 10 times and fails, with no indication of what certificate is causing the issue or how to fix it.

User Setup (Everything Correct Prior to This Error)

The user had completed all required setup steps correctly:

• ✅ Databricks workspace configured
• ✅ databricks auth login completed successfully
• ✅ ~/.databrickscfg populated with a valid profile
• ✅ Claude configured to use Foundation Model APIs (FMAPIs)
• ✅ Databricks profile verified working (CLI commands succeed)

Despite all prerequisites passing, the AI Dev Kit fails at runtime due to SSL issues.

Root Cause

Corporate environments commonly deploy SSL inspection proxies (e.g. Zscaler, Netskope, Palo Alto) that perform man-in-the-middle decryption of HTTPS traffic. These proxies replace the server's TLS certificate with one signed by an internal corporate CA. Unless that corporate CA certificate is trusted by the Python HTTP stack (specifically httpx/requests/certifi), the connection is rejected with a self-signed certificate error.

This affects the outbound HTTPS call from the AI Dev Kit → Databricks FMAPI endpoint → Claude.

Attempted Workaround (from community)

Deleting and re-creating the Databricks auth profile was tried:

databricks auth delete --profile <profile_name>
databricks auth login

This does not fix the issue — the problem is at the TLS/certificate trust layer, not the authentication layer.

Expected Behavior

1. Pre-requisite check or first-run wizard should detect SSL proxy environments and warn the user.
2. The error message should be actionable, pointing users to the correct fix rather than just retrying.
3. The AI Dev Kit should support a configuration option to:
   • Specify a custom CA bundle path (SSL_CERT_FILE / REQUESTS_CA_BUNDLE)
   • Or explicitly document that users in proxy environments need to set these env vars

Suggested Fixes

Option 1 — Detect and surface SSL issues early

During the pre-requisite or connectivity check, make a test HTTPS call and catch SSLError specifically, then output:

❌ SSL Error: A self-signed or untrusted certificate was detected.
   This usually means you are behind a corporate SSL inspection proxy (e.g. Zscaler, Netskope).

   Fix options:
   1. Set your corporate CA bundle:
      export SSL_CERT_FILE=/path/to/corporate-ca-bundle.pem
      export REQUESTS_CA_BUNDLE=/path/to/corporate-ca-bundle.pem

   2. Or append your corporate CA cert to the Python certifi bundle:
      python -m certifi  # shows current bundle path
      cat /path/to/corporate-ca.crt >> $(python -m certifi)

   Then re-run the setup.

Option 2 — Support SSL_CERT_FILE / REQUESTS_CA_BUNDLE configuration

Document and explicitly pass these through to all HTTP clients used by the AI Dev Kit, so users in corporate environments can configure them once without patching certifi.

Option 3 — Pre-req connectivity check

Add a connectivity check step that validates the user can actually reach the Databricks FMAPI endpoint over TLS before proceeding, rather than letting it fail silently at runtime after a long retry loop.

Steps to Reproduce

1. Set up the AI Dev Kit on a machine behind a corporate SSL proxy (Zscaler, Netskope, etc.)
2. Complete all setup steps: databricks auth login, configure FMAPI, etc.
3. Attempt to use Claude via the AI Dev Kit
4. Observe the retry loop and SSL error

Environment

• macOS or Linux behind corporate SSL inspection proxy
• Python httpx/requests using default certifi CA bundle (does not include corporate CA)
• Databricks Foundation Model APIs as the Claude backend
• All Databricks CLI commands work fine (CLI handles SSL separately)

Why This Is Tricky

• The Databricks CLI can succeed (it uses the system keychain or its own cert handling) while Python's certifi-based stack fails — so the user correctly thinks their auth is fine.
• The retry loop (8/10 attempts at 30s each = 4+ minutes of waiting) makes this extremely frustrating to debug.
• There is no pointer in the error message to SSL configuration — users are likely to focus on their Databricks profile/auth, which is a red herring.

References

• REQUESTS_CA_BUNDLE / SSL_CERT_FILE env vars supported by requests and httpx
• python -m certifi to locate the active CA bundle
• Corporate proxy SSL inspection is extremely common in enterprise Databricks customers