Flywheel SSL Certificate Not Working: Fix Local HTTPS Errors

Flywheel SSL Certificate Not Working: Fix Local HTTPS Errors

SSL errors on a Flywheel-related site usually come from one of two very different situations. Local by Flywheel development sites use self-signed certificates, so browsers and operating systems do not trust them by default until you click Trust and the certificate is registered with your computer. Live Flywheel hosting is separate: Local cannot manage remote certificates, and a production site needs a certificate from a trusted certificate authority. Identify which environment you are looking at before changing anything, because the fixes do not overlap.

Which Environment Is Showing the Error?

Start with the browser address and the error text. A URL ending in .local, .dev, or localhost that opens from your machine is almost certainly a Local development site. A public domain with Flywheel hosting or a CDN in front of it is a live site, and local certificate tools have no effect there.

Clue Environment Likely fix direction
Address is example.local or localhost Local by Flywheel Trust the certificate, or fall back to HTTP
Public domain on Flywheel hosting Live hosting Check hosting SSL settings and DNS pointing
Error appears in Flywheel CLI or SDK Flywheel tooling Configure the tool to trust the private CA

The exact error code matters. Local's own documentation recommends noting the actual message the browser reports and using the Advanced button or certificate viewer for detail. Different messages point to different causes, as the sections below explain.

Why Local Sites Show Certificate Warnings

Local creates self-signed certificates so a site can run over HTTPS quickly without buying and configuring a certificate from a third-party certificate authority. A self-signed certificate is like a hand-written ID badge: nothing is inherently wrong with the site, but no outside authority has vouched for the certificate, so the browser cannot confirm identity automatically.

That is why the warning is expected on a fresh Local site. The fix is not to disable browser security globally but to tell your operating system, once, that this specific certificate is trusted.

The Trust Button

Local provides a one-click option for creating and trusting a Local site's certificate: the Trust button under the SSL section of the Site Overview page. On macOS you may be prompted for your administrator password as part of registering the certificate. After clicking Trust, the button should change state to Trusted.

Fixing a Trust Button That Never Turns Trusted

If clicking Trust prompts for a password but the certificate never shows as trusted, something is blocking Local from registering the certificate with the computer. Local's documentation names antivirus software as one possible cause. A quick verification step is to switch to another site and back; a certificate that loses its trusted state after that switch is a strong signal that registration is being prevented.

Work through these checks in order:

  1. Confirm the state persists. Switch sites and return, then reopen the SSL section. If it reverts to untrusted, continue.
  2. Check antivirus or endpoint security. Temporarily pausing HTTPS scanning or certificate protection may allow the registration to complete.
  3. Restart Local and the browser. Some users found browser restarts alone were not enough, so treat this as a step to try rather than a guaranteed fix.
  4. Reset Local's router (macOS). A Local staff reply suggested opening ~/Library/Application Support/Local by Flywheel, removing the routes and router folders, then restarting any site so Local reinitialises the router. This is documented for macOS only, so back up the folders first and expect Local to rebuild them.

If the Trust button still will not stick on macOS, a third-party addon described in a community blog post takes over the trust action and runs an authenticated script that trusts the certificate in the System keychain. It is not an official Local tool and its reliability is not verified, so use it only as a last resort after the official steps. For Windows, the supplied troubleshooting guidance does not cover the certificate store, so manual Windows certificate steps need separate verification.

Fixing ERR_SSL_Protocol_ERROR and Secure Connection Failures

ERR_SSL_PROTOCOL_ERROR indicates something is wrong with the SSL certificate for that Local site. The same symptom can appear as "This site can't provide a secure connection." One user on Local 9.1.0 saw the front end load with an untrusted SSL alert while wp-admin failed with the secure connection message. Another hit the same error on a .dev domain when opening the admin login screen, and a Stack Overflow report shows the identical string for localhost.

The error often follows a site import. One user who imported a full site download from WP Engine could open the front end but not wp-admin, which returned ERR_SSL_PROTOCOL_ERROR.

Workaround: Use HTTP Locally

If you do not need HTTPS on your development machine, a Local staff reply suggested replacing https references with http. From Local's Open site shell, run a search-replace with your own site address:

wp search-replace 'https://example.local' 'http://example.local'

Substitute your actual local URL. This changes stored references so WordPress stops forcing HTTPS, which sidesteps the certificate problem for local work. Do not carry this change to production.

When the Workaround Does Not Help

Some users tried other fixes without success. One changed the protocol in site settings through Adminer and cleared Chrome's Domain Security Policies for localhost, and the error remained. In that situation, a Local staff reply suggested upgrading to the latest versions of Local and macOS as a possible resolution.

Domain Naming Observations

Community reports include domain changes, but treat them as individual experiences rather than official advice. One user renamed a project folder and switched the site address to a .local domain, which appeared to fix their SSL error. Another reported success changing from .dev to .local. A Local staff reply clarified that a .local top-level domain is not required for trusting certificates. If you try a domain change, use Local's site settings rather than editing files by hand.

When the Problem Is on Live Flywheel Hosting

Local cannot manage SSL certificates for remote environments. If a public site shows an HTTPS error, the certificate has to come from a trusted certificate authority and be installed on the hosting side. Local's Trust button has no effect on a remote site.

If a Local site was created without SSL but the admin or site buttons keep opening over HTTPS, that is a different symptom: one user reported exactly this forced-HTTPS behaviour. Check the site's SSL section in Local and whether the site URL in WordPress still starts with https.

Live hosting settings such as Force HTTPS, redirect loops, and Simple SSL DNS warnings are not detailed in the available troubleshooting material. For those, the practical checks are the domain's DNS records, whether the domain resolves to the Flywheel site, and the SSL status shown in the Flywheel dashboard. Escalate to Flywheel support if the dashboard shows no certificate issued for the domain.

Flywheel CLI and SDK Certificate Errors (Separate Case)

If you see CERTIFICATE_VERIFY_FAILED in Flywheel command-line tools or the SDK rather than in a browser, the cause is different. Flywheel uses public certificates signed by globally trusted certificate authorities, and this error typically occurs when an organisation performs TLS interception by inserting certificates signed by a private certificate authority into the trust chain.

The resolution is to configure the CLI or SDK to trust that private CA. Depending on the tool version, that means options such as CA_CERTS_BUNDLE or --ca-certs for the legacy CLI, and --ssl-cert or FW_CLI_SSL_CERT for the new CLI. Two version notes matter:

  • Before Flywheel Core 22.4.0, gear install, gear update, and gear upload could fail with this error even when certificate options were configured.
  • From Flywheel Core 22.3.0, the new CLI validates against the operating system's default trust store and no longer uses --ssl-verify.

Flywheel's documentation also warns against using REQUESTS_CA_BUNDLE, because it replaces the trust store globally instead of adding to it and can break uploads to cloud storage. Use the tool-specific options instead.

How to Confirm the Fix

Verification is quick and worth doing before you move on.

  1. Check the Trust state. Return to the Site Overview and confirm the SSL section shows Trusted.
  2. Switch sites and back. If it reverts, registration is still being blocked.
  3. Inspect the certificate. Open the browser's certificate viewer and confirm the certificate matches the local site address.
  4. Reload both front end and admin. Load the home page and wp-admin separately, since one can fail while the other loads.
  5. Note the exact error if it returns. The precise message narrows the cause faster than a general "not secure" label.

If HTTPS is not essential for local development, reverting the site to HTTP is a legitimate end state for a development environment. Keep the HTTPS configuration documented so it can be restored when you need to test secure-cookie behaviour or redirects.

What Local Cannot Do

Local's SSL tooling is scoped to development sites. It cannot manage certificates for remote environments, and production servers should use a certificate from a trusted certificate authority. Two practical consequences follow.

First, never treat a trusted Local certificate as evidence that a live site's certificate is correctly configured. They are independent.

Second, do not copy local certificate workarounds, such as an HTTP search-replace, into a production database. Do those operations locally and push only intended content changes. When in doubt about which environment you are touching, check the site URL before running any command.

Leave a Comment

Your email address will not be published. Required fields are marked *

Scroll to Top