Troubleshoot the Confluent CLI

Solutions

Verify the Confluent CLI version

Always verify which Confluent CLI version the you are running, along with operating system (OS) version and architecture. The release notes describe changes for each new version of the Confluent CLI.

  • You can check the Confluent CLI version by running:

    confluent version

  • If the issue persists, and you are not running the latest version of the Confluent CLI, update to the latest minor version:

    confluent update

    (If you want to update to the latest major version, use the same command with the --major flag.) Keep in mind that referenced commands in this Troubleshooting Guide also indicate the current version command names and flags.

  • To find the OS and architecture version:

    For Linux/macOS or Linux on Windows through WSL, the uname command:

    # command
uname -a

    Sample output:

    Darwin C02D367KMD6T 23.6.0 Darwin Kernel Version 23.6.0: Mon Jul 29 21:13:00 PDT 2024; root:xnu-10063.141.2~1/RELEASE_X86_64 x86_64

Errors at login after Confluent CLI upgrade

If the you get errors after a CLI upgrade, try removing or renaming the file ~/.confluent/config.json and try to login again with confluent login. Sometimes this file can get corrupted and cause unpredictable errors.

Obtain trace logs

You can get verbose logs by adding the -vvvv flag to commands.

You also can get trace logs by adding the --unsafe-trace flag to a command, which is equivalent to -vvvv, but also logs HTTP requests and responses which might contain plaintext secrets. If you use this option, be sure to redact the secrets before sharing the output with Confluent Support.

Connectivity issue and misleading error: API key may not be provisioned yet

If you see the following error from the Confluent CLI:

Error: failed to obtain topics from client: API key may not be provisioned yet

This error message can be misleading. If the in use API Keys look valid, ask for the verbose output and check for any additional information. Often the real problem is a connectivity issue.

Make sure your firewalls allow connectivity to the required endpoints and ports

When Confluent CLI interacts with Confluent Cloud, it requires network access to the following public domains:

  • confluent.cloud (port 443 and 9092 for audit logs)
  • login.confluent.io when using SSO (port 443)
  • api.stripe.com when using the confluent billing payment commands
  • s3-us-west-2.amazonaws.com/confluent.cloud when the update check is enabled

Therefore, make sure that your firewall allows connection to the above endpoints/ports. The following curl command should return an HTTP 200 response code and some HTTP headers.

curl -X GET --head https://confluent.cloud

If the above command returns any other code or error, then connectivity to the host is the cause of the problem. In that case, check any firewalls or network configurations that may be preventing the Confluent CLI to reach that domain.

Following are some other tests to validate that egress to https://login.confluent.io is allowed:

telnet login.confluent.io 443

openssl s_client -connect login.confluent.io:443

curl -verbose -XPOST "https://login.confluent.io/oauth/token"

If you get the following error when you log in as an SSO user, this usually indicates that the above endpoints/ports are not whitelisted on the firewall.

Error: failed to get oauth token: Post"https://login.confluent.io/oauth/token": EOF

Note that currently the IP address for login.confluent.io is not static and could change anytime.

Check for proxy interference indicated by Error: Certificate signed by unknown authority

The following error usually indicates that a proxy on your end is interfering with Confluent CLI certificates information.

Error: Post "https://confluent.cloud/api/sessions": x509: certificate signed by unknown authority

Confluent Cloud certificates are signed by Let’s Encrypt CA, which should be included in most Linux distributions.

The following error indicates that the certificate expected by Confluent Cloud is not in your Operating System and/or CA truststore.

Verify return code: 20 (unable to get local issuer certificate)

Confluent Cloud serves the following chain of trust:

Certificate chain
0 i:/C=US/O=Let's Encrypt/CN=R3
1 i:/C=US/O=Internet Security Research Group/CN=ISRG Root X1

Identify cluster connection issues

When performing data plane operations like produce/consume, errors like following in the verbose output, indicate that there is an issue related to connecting to the cluster endpoint.

CONNECT|Confluent-CLI_v3.6.0#consumer-1| [thrd:app]: Not selecting any broker for cluster connection: still suppressed for 49ms: application metadata request

The Confluent CLI needs to be able to connect to both the Cluster Bootstrap Endpoint (port 9092) and the REST Endpoint (port 443). You can test connectivity from the host by running the Confluent CLI as described in :cloud|`Test Connectivity to Confluent Cloud|networking/testing.html`.

  • If the cluster is private, by default it is possible to connect to the cluster only from an instance inside the VPC.
  • If the host running the Confluent CLI (or the client) is located outside the VPC (an external network or on-premises), you must implement additional network configuration to provide connectivity.

However, configuring or troubleshooting connections from on-premises or from external networks to Confluent Cloud clusters with private networking implemented, such as VPC Peering, VNet Peering, or Private Links, is outside the support scope, as documented in the “important” information block under Confluent Cloud Support for Self-managed components.

Confluent CLI login is limited to user accounts (service accounts cannot be used)

Service accounts cannot be used to log in to the Confluent CLI, only user accounts can log in with a user name and password or SSO.

You can use API keys to produce and consume from a topic using using user-agnostic contexts. However, this is limited to produce and consume; for all the other operations, a user login is required.

Log in with the --organization-id flag to target the correct organization for login

A user account can be part of multiple Confluent Cloud organizations. In such cases, make sure you are attempting logins to the correct organization by adding the --organization-id flag to confluent login command.

Save login credentials or remove config file if you get errors at login

When you log in to the Confluent CLI with the --save flag, your credentials are stored in $HOME/.confluent/config.json. This allows you to skip providing your credentials each time you log in.

If you get errors at login for incorrect email, password, or organization ID, contact Confluent Support or file a GitHub issue against the confluentinc/cli.

Verify that .confluent is in your HOME directory

Make sure the following command returns /usr/bin/confluent:

which confluent

.confluent should be located under your HOME directory. If you have an environment variable set for .confluent, you will see it in the results for this command:

env | grep HOME

Or, use the following command to list all files in your HOME directory , including hidden files preceded by a dot (.). You should see .confluent listed.

ls -al $HOME