Fix SWG TLS & SSL certificate errors in CLI and AI tools on a Mac

Troubleshoot CERTIFICATE_VERIFY_FAILED and local issuer certificate errors in git, npm, Python, Claude Code, and Cursor behind an SWG on macOS.

SWG bar · Updated

When a company Mac sits behind a Secure Web Gateway (SWG) performing HTTPS/SSL inspection (break-and-inspect), Safari and Chrome often load websites without a warning while Terminal tools and AI coding agents fail with TLS handshake errors such as SSL: CERTIFICATE_VERIFY_FAILED, UNABLE_TO_GET_ISSUER_CERT_LOCALLY, or SSL certificate problem: unable to get local issuer certificate.

This mismatch happens because browsers consult macOS Keychain—where MDM can install your organization’s inspection root CA—whereas many command-line runtimes (git, curl, Node.js/npm, Python/pip) and AI tools (Claude Code, Cursor, MCP servers) validate certificates against their own bundled public CA stores.

1. Confirm which hostname is undergoing HTTPS inspection

Before changing environment variables or network settings, verify whether the failing endpoint’s certificate chain is actually being replaced on your Mac:

  1. Install and open SWG bar on macOS 14 or later (Apple silicon).
  2. Run the failing command once, then check SWG bar → Domains—or probe the exact endpoint directly from Terminal using the bundled CLI:
/Applications/SWGBar.app/Contents/MacOS/swgbar probe registry.npmjs.org
/Applications/SWGBar.app/Contents/MacOS/swgbar domains detail registry.npmjs.org
  1. Inspect the classification and root CA. Remember that web frontends, authentication servers, package registries, and LLM API endpoints often use different hostnames—one subdomain may pass through untouched while another is decrypted.

If you use an MCP-compatible assistant, you can also connect SWG bar’s built-in MCP server so your AI client can query observed domains and certificate chains directly.

2. Choose the right fix for your environment

Once you confirm that an inspection root CA is signing the target hostname’s certificate, choose one of three approaches depending on your network policy and authorization:

Approach How it works Best when
Configure CA trust for the tool Point the runtime (for example NODE_EXTRA_CA_CERTS, SSL_CERT_FILE, or REQUESTS_CA_BUNDLE) to an exported PEM bundle that includes the corporate root CA. Corporate policy requires inspected SWG routing and you trust that CA for the specific tool.
Request an admin TLS inspection exception IT excludes the API or registry hostname from HTTPS decryption on the gateway while keeping gateway routing. Certificate-pinned tools or team-wide developer endpoints break under break-and-inspect.
Enable per-domain SWG bypass in SWG bar Routes the selected hostname on macOS without gateway HTTPS decryption via menu bar, CLI, or MCP. You administer or are authorized to test an uninspected route for specific domains on your Mac.

Read SWG bypass vs. TLS inspection exception for a detailed architectural comparison of gateway exceptions and route changes.

3. Bypass an inspected domain on macOS when authorized

If per-domain bypass is appropriate for your network, you can enable it for the exact API or registry hostname from the menu bar (SWG bar → Domains → Bypass SWG → Enable) or from Terminal:

/Applications/SWGBar.app/Contents/MacOS/swgbar bypass enable registry.npmjs.org
/Applications/SWGBar.app/Contents/MacOS/swgbar bypass status

After the status shows Bypassing, restart the CLI command, background daemon, or IDE extension host so existing connections close and reconnect over the new rule. Follow How to bypass SWG on a Mac for first-time macOS network extension approval, restart behavior, and how to turn bypass off when finished.

Keep platform and network boundaries in mind

  • Per-hostname scope: Bypassing example.com does not automatically include api.example.com or auth.example.com. Check each hostname your tool contacts.
  • Network requirements: SWG bar 2.4.12 requires macOS 14+ on Apple silicon and an available IPv4 path over a physical network interface. If a firewall blocks direct outbound connections or the tool enforces its own explicit proxy, disable the bypass rule and use an administrator TLS exception or CA bundle configuration instead.
  • Verify with fresh evidence: Run a fresh check using the HTTPS & SSL inspection guide after any change rather than relying on cached results.