FIELD NOTES & GUIDES

Local HTTPS Without the Headache

Fix the terminal errors first. Understand why certificate trust, DNS, and WebSockets break. Then keep the fix.

• How to enable trusted HTTPS on localhost in Safari and Chrome on macOS

  Generate a local CA, sign leaf certificates with correct Subject Alternative Names, and import them into the macOS Login Keychain with CLI tools.

• mkcert Alternative with a Native macOS GUI

  Why mkcert is only half the battle: automating Keychain trust, reverse proxying port 443, wildcard DNS, and mobile device profiles.

• How to set up HTTPS in Vite local dev without certificate errors

  Fix Vite dev server HTTPS warnings and broken WebSocket Hot Module Replacement (HMR) across your frontend applications.

• How to fix untrusted SSL certificates on iOS Simulator and physical iPhone

  Install and enable full root certificate authority trust on iOS Simulators via simctl and on real iPhones via Apple .mobileconfig profiles.

• How to configure /etc/resolver for .test domains on macOS

  Route an entire development top-level domain (*.test) to localhost without editing /etc/hosts for every new project.

• Fix WebSocket and HMR connection failed behind HTTPS reverse proxy

  Diagnose and resolve WebSocket dropouts, 101 Switching Protocols failures, and Fast Refresh crashes behind TLS termination proxies.

• Next.js local HTTPS for Secure and SameSite cookies in development

  Eliminate OAuth redirect mismatch errors, WebAuthn failures, and dropped SameSite=None; Secure cookies during local Next.js development.

• Why can't I use .dev for local development?

  .dev and .app are real TLDs on the HSTS preload list, so browsers force HTTPS. Why .test and .localhost are the safe choices, and how to make .test resolve on a Mac.

• Fix "unable to verify the first certificate" in Node, curl and Python with a local CA on macOS

  Node.js, Homebrew curl, Python and Java ignore the macOS keychain. Point each at your root CA file with NODE_EXTRA_CA_CERTS, --cacert, REQUESTS_CA_BUNDLE or keytool.

• Fix NET::ERR_CERT_AUTHORITY_INVALID on localhost in Chrome on Mac

  Find out which certificate your server sends and who signed it, then fix the cause: a self-signed certificate, a CA that is imported but not trusted, or trust on the wrong certificate or account.

• How to trust a self-signed certificate or local CA in Keychain on a Mac

  Set trust with security add-trusted-cert or Keychain Access, choose between the login and System keychains, and see which browsers and tools then accept the certificate.

• Fix Python "CERTIFICATE_VERIFY_FAILED: unable to get local issuer certificate" on Mac

  Run Install Certificates.command for python.org installs, choose REQUESTS_CA_BUNDLE or SSL_CERT_FILE for a local CA, or use truststore to read the macOS keychain.

• How to make a Docker container trust your local development CA

  Copy the root CA into Debian and Alpine images with update-ca-certificates, cover Node and pip-installed requests, and connect with a name the certificate matches.

• Use app.localhost subdomains on a Mac without editing /etc/hosts

  Current macOS resolves every .localhost name to this Mac. Check it with dscacheutil rather than dig, handle the ::1-first catch and Vite's allowed hosts, and name each subdomain in the certificate because *.localhost is refused.

• Fix "SEC_ERROR_UNKNOWN_ISSUER" in Firefox when Safari and Chrome already trust your local certificate on a Mac

  Firefox keeps its own certificate store and only imports macOS roots at launch when its enterprise roots setting is on. Check the setting, import the CA in Certificate Manager or with certutil, or push it with policies.json.

• Fix "PKIX path building failed: unable to find valid certification path to requested target" with a local CA on a Mac

  Java reads the JDK's cacerts file, not the keychain. Find which JDK is really running, import the root CA with keytool -cacerts, stop the Gradle daemon, and repeat after every JDK upgrade.

• Fix ERR_SSL_PROTOCOL_ERROR on localhost: "This site can't provide a secure connection" on a Mac

  The browser is speaking HTTPS to a dev server that only speaks HTTP. Confirm it with curl, find what forced https://, and see when clearing HSTS helps and when it cannot.