<a id="cli-troubleshoot"></a>

# Troubleshoot the Confluent CLI

## Quick List: CLI install and operation

- [Verify the Confluent CLI version](#cli-verify-version)
- [Errors at login after Confluent CLI upgrade](#cli-login-errors)
- [Obtain trace logs](#cli-get-verbose-logs)
- [Connectivity issue and misleading error: API key may not be provisioned yet](#cli-api-key-provisioning-error)
- [Make sure your firewalls allow connectivity to the required endpoints and ports](#cli-connectivity)
- [Check for proxy interference indicated by Error: Certificate signed by unknown authority](#cli-proxy-interfering-with-certificates)
- [Identify cluster connection issues](#cli-cluster-connectivity)
- [Identify connectivity to PrivateLink clusters indicated by SSL handshake errors starting with e-](#cli-private-link-cluster-connectivity)
- [Confluent CLI login is limited to user accounts (service accounts cannot be used)](#cli-user-accounts-login)
- [Log in with the --organization-id flag to target the correct organization for login](#cli-user-accounts-and-multiple-orgs)
- [Save login credentials or remove config file if you get errors at login](#cli-saved-login-credentials)
- [Verify that .confluent is in your HOME directory](#cli-verify-confluent-in-home-dir)

## Quick List: CLI command errors

- [Set active environment for commands that use both region and cloud flags](#command-region-cloud-flags)

## Solutions for CLI install and operation

<a id="cli-verify-version"></a>

### 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](release-notes.md#cli-release-notes) describe changes for each new version of the Confluent CLI.

- You can check the Confluent CLI version by running:
  ```bash
  confluent version
  ```
- If the issue persists, and you are not running the latest version of the Confluent CLI, [update](command-reference/confluent_update.md#confluent-update) to the latest minor version:
  ```bash
  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:

  ### Linux/macOS or Windows

  For Linux/macOS or Linux on Windows through WSL, the `uname` command:
  ```text
  # command
  uname -a
  ```

  Sample output:
  ```text
  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
  ```

  ### Windows

  For Windows using PowerShell or the Command Prompt:
  - Find the OS version:
    ```bash
    systeminfo | findstr /B /C:"OS Name" /C:"OS Version"
    ```
  - Find architecture version:
    ```bash
    echo %PROCESSOR_ARCHITECTURE%
    ```

<a id="cli-login-errors"></a>

### 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.

<a id="cli-get-verbose-logs"></a>

### 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.

<a id="cli-api-key-provisioning-error"></a>

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

If you see the following error from the Confluent CLI:

```bash
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.

<a id="cli-connectivity"></a>

### 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](command-reference/billing/index.md#confluent-billing) commands
- `s3-us-west-2.amazonaws.com/confluent.cloud` when the [update check](overview.md#cli-update-check) is enabled

Therefore, make sure that your firewall allows connection to the above endpoints/ports.
The following [curl command](https://curl.se/) should return an `HTTP 200` response code and some HTTP headers.

```bash
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](https://login.confluent.io) is allowed:

```bash
telnet login.confluent.io 443
```

```bash
openssl s_client -connect login.confluent.io:443
```

```bash
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.

```bash
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.

<a id="cli-proxy-interfering-with-certificates"></a>

### 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.

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

Confluent Cloud certificates are signed by [Let’s Encrypt CA](/cloud/current/cp-component/clients-cloud-config.html),
which should be included in most Linux distributions.

- On Linux based systems, the CA path is typically as follows:
  ```bash
  /etc/ssl/certs
  ```
- Windows certificates are located in the [Trusted Root Certification Authorities certificate store](https://learn.microsoft.com/en-us/windows-hardware/drivers/install/trusted-root-certification-authorities-certificate-store).

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

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

Confluent Cloud serves the following chain of trust:

```none
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
```

<a id="cli-cluster-connectivity"></a>

### 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.

```bash
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](/cloud/current/support.html#self-managed-components).

<a id="cli-private-link-cluster-connectivity"></a>

### Identify connectivity to PrivateLink clusters indicated by SSL handshake errors starting with `e-`

If producing or consuming with the Confluent CLI shows SSL handshake errors on v4 broker dns scheme that starts with `e-`,
such as in the following example:

```bash
e-$last2octets-$zoneid-$nid.$region.$cloud.glb.confluent.cloud
```

This indicates you are trying to perform data plane operations against a “PrivateLink” cluster and either:

- The host may not have connectivity to the cluster.

Or

- The “PrivateLink” configuration is incorrect.

Contact Confluent Support for help with PrivateLink troubleshooting.

<a id="cli-user-accounts-login"></a>

### 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.

<!-- .. _cli-api-keys-for-produce-and-consume: -->
<!-- Use API keys for produce and consume from the |confluent-cli| if desired -->
<!-- ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -->

You can use API keys to produce and consume from a topic using
[using user-agnostic contexts](/cloud/current/security/access-control/cli-multiple-credentials.html#user-agnostic-api-keys-for-produce-and-consume).
However, this is limited to [produce](command-reference/kafka/topic/confluent_kafka_topic_produce.md#confluent-kafka-topic-produce) and [consume](command-reference/kafka/topic/confluent_kafka_topic_consume.md#confluent-kafka-topic-consume);
for all the other operations, a user login is required.

<a id="cli-user-accounts-and-multiple-orgs"></a>

### 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-reference/confluent_login.md#confluent-login) command.

<a id="cli-saved-login-credentials"></a>

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

When you [log in](command-reference/confluent_login.md#confluent-login) 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](https://github.com/confluentinc/cli).

<a id="cli-verify-confluent-in-home-dir"></a>

### Verify that `.confluent` is in your HOME directory

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

```bash
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:

```bash
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.

```bash
ls -al $HOME
```

## Solutions for command errors

<a id="command-region-cloud-flags"></a>

### Set active environment for commands that use both `region` and `cloud` flags

Confluent Cloud commands that use the `--region` and `cloud` flags require an active environment.

For example, when using the command [confluent flink region list](https://docs.confluent.io/confluent-cli/current/command-reference/flink/region/confluent_flink_region_list.html),
note that `confluent flink region list --cloud aws` requires an active environment ([confluent environment use <environment-ID>](https://docs.confluent.io/confluent-cli/current/command-reference/environment/confluent_environment_use.html)).

First, specify the environment you want to use. Then list the regions.

```bash
confluent environment use env-abc123
Using environment env-abc123.

confluent flink region list --cloud aws
Current |            Name            | Cloud |     Region
----------+----------------------------+-------+-----------------
         | Canada (ca-central-1)      | AWS   | ca-central-1
         | Frankfurt (eu-central-1)   | AWS   | eu-central-1
         | Ireland (eu-west-1)        | AWS   | eu-west-1
         | London (eu-west-2)         | AWS   | eu-west-2
         | Mumbai (ap-south-1)        | AWS   | ap-south-1
```

Following is the error you will get when attempting to list regions for a specific `--cloud` parameter (like `aws`), without first specifying the current environment:

```bash
confluent flink region list --cloud aws
Error: no environment found
```

Alternatively, `confluent flink region list`  (without the `--cloud` flag) does not need an active environment. This command will yield a list of regions, regardless of whether you have specified an active environment.