Skip to content

SSL/TLS Certificate Validation Issues with Flywheel CLI Tools

If you encounter SSL/TLS certificate validation errors when using Flywheel CLI tools, this article will help you resolve the issue.

Understanding the Issue

You may experience certificate validation errors even though Flywheel uses public certificates signed by globally-trusted certificate authorities. This typically occurs when your organization performs TLS interception and deep packet inspection by inserting certificates signed by a private certificate authority into the trust chain.

When the Flywheel CLI attempts to validate the certificate presented by your Flywheel Core site, it cannot validate certificates signed by your organization's private certificate authority unless properly configured.

Identifying the Issue

You may encounter error messages similar to these when this certificate validation issue occurs:

1
2
3
4
5
6
7
WARNING Retrying after connection broken by 'SSLError(SSLCertVerificationError(1,
'[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self-signed certificate in certificate chain'))': /api/users/self

Error logging in: GET https://your-site.flywheel.io:443/api/users/self -
HTTPSConnectionPool(host='your-site.flywheel.io', port=443): Max retries exceeded with url: /api/users/self
(Caused by SSLError(SSLCertVerificationError(1, '[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed:
self-signed certificate in certificate chain')))

If you see messages containing CERTIFICATE_VERIFY_FAILED or self-signed certificate in certificate chain, this indicates the SSL/TLS certificate validation issue described in this article.

The Solution

To resolve this issue, you need to configure the Flywheel CLI to trust your organization's private certificate authority. In most cases, your IT department has already installed the necessary CA certificate bundle on your computer, so you typically only need to configure the CLI to use it.

Configuration by CLI Version

Flywheel provides two CLI tools with different configuration methods:

Legacy CLI (fw)

Configure the legacy CLI using one of these methods:

Option 1: Environment Variable

1
2
export REQUESTS_CA_BUNDLE=/path/to/your/ca-bundle.pem
fw <command>

Option 2: Command-line Option

1
fw --ca-certs /path/to/your/ca-bundle.pem <command>

New CLI (flyw)

Configure the new CLI using one of these methods:

Option 1: Environment Variable

1
2
export FW_CLI_SSL_VERIFY=/path/to/your/ca-bundle.pem
flyw <command>

Option 2: Command-line Option

1
flyw --ssl-verify /path/to/your/ca-bundle.pem <command>

Finding Your CA Certificate Bundle

Your organization's CA certificate bundle is typically located in one of these common locations:

If you cannot locate the certificate bundle, contact your IT department for assistance.

Windows: Identifying and Exporting Your Organization's Root CA Certificate

If your organization uses TLS interception, you can identify and export the root CA certificate directly from Windows.

Step 1: Identify the Root CA Certificate

  1. Open a web browser and navigate to your Flywheel instance URL (for example, https://your-site.flywheel.io).

  2. Click the padlock icon in the browser's address bar.

  3. Click Connection is secure (or similar, depending on your browser).

  4. Click the certificate icon or View certificate to open the Certificate Viewer.

  5. In the Certificate Viewer, click the Details tab.

  6. Look at the Certificate Hierarchy section at the top. The topmost entry is your organization's root CA certificate. Note the name of this root CA certificate—you will need it in the next step.

Step 2: Find the Certificate in Windows Certificate Manager

  1. Open Command Prompt or PowerShell.

  2. Type certmgr and press Enter to open the Windows Certificate Manager.

  3. In the left panel, expand Trusted Root Certification Authorities.

  4. Click Certificates to view all trusted root certificates.

  5. Locate the root CA certificate you identified in Step 1.

Step 3: Export the Certificate

  1. Right-click the root CA certificate and select All Tasks > Export.

  2. In the Certificate Export Wizard, click Next.

  3. Select Base-64 encoded X.509 (.CER) format and click Next.

  4. Choose a location and filename for the exported certificate (for example, C:\Users\<username>\corporate-root-ca.cer).

  5. Click Next, then Finish to complete the export.

Step 4: Configure Environment Variables

After exporting the certificate, configure the environment variables to point to the exported certificate file.

Temporary Configuration (Current Session Only)

In PowerShell:

1
2
$env:FW_CLI_SSL_VERIFY="C:\Users\<username>\corporate-root-ca.cer"
$env:REQUESTS_CA_BUNDLE="C:\Users\<username>\corporate-root-ca.cer"

In Command Prompt:

1
2
set FW_CLI_SSL_VERIFY=C:\Users\<username>\corporate-root-ca.cer
set REQUESTS_CA_BUNDLE=C:\Users\<username>\corporate-root-ca.cer

Permanent Configuration

To set these environment variables permanently:

  1. Open System Properties > Advanced > Environment Variables (or search for "Environment Variables" in the Windows Start menu).

  2. Under User variables, click New.

  3. Add the following variables:

    • Variable name: FW_CLI_SSL_VERIFY
    • Variable value: C:\Users\<username>\corporate-root-ca.cer

  4. Repeat to add REQUESTS_CA_BUNDLE with the same path.

  5. Click OK to save your changes.

  6. Restart any open terminal windows for the changes to take effect.

Linux: Identifying and Exporting Your Organization's Root CA Certificate

On Linux you can export the certificate chain directly from your Flywheel site, then install it where the CLI and the tools it invokes will find it.

Step 1: Export the certificate chain

Capture the full certificate chain presented by your site—not just the server's own certificate. Exporting only the leaf certificate will leave validation failing with errors such as self-signed certificate in certificate chain. Replace your-site.flywheel.io with your Flywheel hostname:

1
2
3
HOST=your-site.flywheel.io
openssl s_client -connect "$HOST:443" -servername "$HOST" -showcerts </dev/null 2>/dev/null \
  | awk '/-----BEGIN CERTIFICATE-----/,/-----END CERTIFICATE-----/' > flywheel-ca-chain.pem

Confirm the chain validates. You should see Verify return code: 0 (ok):

1
2
openssl s_client -connect "$HOST:443" -servername "$HOST" -CAfile flywheel-ca-chain.pem </dev/null 2>&1 \
  | grep "Verify return code"

Step 2: Configure the CLI to use the certificate

Point the CLI at the exported file for the current session:

1
2
export FW_CLI_SSL_VERIFY=/path/to/flywheel-ca-chain.pem
export REQUESTS_CA_BUNDLE=/path/to/flywheel-ca-chain.pem

To make this permanent, add the same two lines to your shell profile (for example ~/.bashrc or ~/.zshrc) and restart your terminal.

Step 3: Install the certificate system-wide

The environment variables above apply only to the CLI's own commands. Other tools the CLI calls out to—most notably docker and docker buildx, used by flyw gear upload—ignore those variables and validate against the operating system trust store. Install the certificate there as well so those tools trust your site:

RHEL / CentOS / Fedora:

1
2
sudo cp flywheel-ca-chain.pem /etc/pki/ca-trust/source/anchors/flywheel-ca.crt
sudo update-ca-trust extract

Debian / Ubuntu:

1
2
sudo cp flywheel-ca-chain.pem /usr/local/share/ca-certificates/flywheel-ca.crt
sudo update-ca-certificates

For flyw gear upload, Docker also reads per-registry certificates from /etc/docker/certs.d/<your-site>/ca.crt. Copying the chain to that path as well lets docker login and docker push validate the registry. Note that docker buildx does not read this location, so the system-wide install above is still required.

Security Warning

Disabling SSL verification is not recommended for production use. Only use this option for development or testing environments without sensitive data.

Both of Flywheel's CLI tools allow you to disable SSL verification entirely by setting the --ssl-verify false command-line option.

Getting Help

If you continue to experience certificate validation issues after trying these solutions:

  1. Verify the path to your CA certificate bundle is correct
  2. Ensure the certificate bundle file is readable by your user account
  3. Contact your IT department to confirm the certificate bundle installation
  4. Contact Flywheel support for additional assistance