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 (fw-beta)

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
fw-beta <command>

Option 2: Command-line Option

1
fw-beta --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:

  • Windows: C:\path\to\ca-bundle.pem (contact your IT department for the exact path)
  • 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

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

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