SSL/TLS Certificate Validation Issues with Flywheel CLI Tools and SDK

If you encounter SSL/TLS certificate validation errors when using Flywheel CLI tools or the Flywheel SDK, 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 or SDK 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 or SDK 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 tool to use it.

Configuration by Tool

Flywheel provides two CLI tools and a Python SDK, each 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 to trust your organization's CA bundle using one of these methods.

Option 1: Command-line Option

The --ssl-cert option takes the path to a CA certificate bundle and can be repeated to trust more than one bundle:

1

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

Option 2: Environment Variable

1
2

export FW_CLI_SSL_CERT=/path/to/your/ca-bundle.pem
flyw <command>

Option 3: Persist in the CLI Configuration

To trust the certificate for every flyw command without setting it each time, save it to the CLI configuration:

1

flyw config set ssl_cert /path/to/your/ca-bundle.pem

After configuring the certificate, confirm the CLI can establish a trusted connection with the flyw utils verify-ssl command:

1

flyw utils verify-ssl https://your-site.flywheel.io

Flywheel SDK

Configure the Flywheel SDK by setting the FW_SSL_CERT_FILE environment variable to the absolute path of your CA certificate bundle:

1

export FW_SSL_CERT_FILE=/path/to/your/ca-bundle.pem

Finding Your CA Certificate Bundle

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

• Windows: See Windows: Identifying and Exporting Your Organization's Root CA Certificate below
• macOS: /usr/local/share/ca-certificates/ or contact your IT department
• Linux: /etc/ssl/certs/ca-certificates.crt or /etc/pki/tls/certs/ca-bundle.crt, or see the Linux section below

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. Set FW_CLI_SSL_CERT and REQUESTS_CA_BUNDLE for the CLI tools, and FW_SSL_CERT_FILE for the SDK.

Temporary Configuration (Current Session Only)

In PowerShell:

1
2
3

$env:FW_CLI_SSL_CERT="C:\Users\<username>\corporate-root-ca.cer"
$env:REQUESTS_CA_BUNDLE="C:\Users\<username>\corporate-root-ca.cer"
$env:FW_SSL_CERT_FILE="C:\Users\<username>\corporate-root-ca.cer"

In Command Prompt:

1
2
3

set FW_CLI_SSL_CERT=C:\Users\<username>\corporate-root-ca.cer
set REQUESTS_CA_BUNDLE=C:\Users\<username>\corporate-root-ca.cer
set FW_SSL_CERT_FILE=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_CERT
   • Variable value: C:\Users\<username>\corporate-root-ca.cer

4. Repeat to add REQUESTS_CA_BUNDLE with the same path.

5. Repeat again to add FW_SSL_CERT_FILE with the same path for the SDK.

6. Click OK to save your changes.

7. 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, the SDK, and the tools the CLI 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 and SDK to use the certificate

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

1
2
3

export FW_CLI_SSL_CERT=/path/to/flywheel-ca-chain.pem
export REQUESTS_CA_BUNDLE=/path/to/flywheel-ca-chain.pem
export FW_SSL_CERT_FILE=/path/to/flywheel-ca-chain.pem

To make this permanent, add the same three 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 and the SDK. 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.

Disabling SSL Verification (Not Recommended)

The way to disable SSL verification depends on which CLI you use:

• New CLI (flyw) — use the --insecure option (added in version 22.3.0):

  1	flyw --insecure <command>

• Legacy CLI (fw) — use the --ssl-verify false option:

  1	fw --ssl-verify false <command>

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

Related Information

• For more CLI configuration options, see the Legacy CLI and New CLI documentation.
• For more SDK usage information, see the Flywheel SDK documentation.