> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/harness-platform/3.0/harness-cli/cli/troubleshooting.md).

# Troubleshooting

Learn how to diagnose and resolve common Harness CLI errors, understand exit codes, and enable debug logging for detailed request information.

Use this page to diagnose and resolve common Harness CLI issues. Most problems fall into one of four categories: authentication failures, scope and context issues, network connectivity problems, or incorrect resource identifiers.

## What you will learn in this topic

By the end of this page, you will know how to:

* Interpret CLI exit codes and error messages.
* Collect diagnostic information using debug logging.
* Resolve common authentication, scope, and network issues.
* Troubleshoot resource identifier, YAML validation, and version-related errors.

## Before you begin

* **Harness CLI installed:** For installation steps, see [Install and upgrade](/harness-platform/3.0/harness-cli/cli/overview.md).

### Quick troubleshooting workflow

When a command fails unexpectedly:

{% stepper %}
{% step %}

## Re-run the command with debug logging

Re-run the command with `--debug`.
{% endstep %}

{% step %}

## Verify authentication

Verify authentication with `harness auth status`.
{% endstep %}

{% step %}

## Confirm scope and context

Confirm the correct organization, project, and resource level.
{% endstep %}

{% step %}

## Verify the resource exists

Verify that the resource exists using the corresponding `list` command.
{% endstep %}

{% step %}

## Check the CLI version

Check your CLI version with `harness --version`.
{% endstep %}
{% endstepper %}

### Exit codes

The CLI uses standard exit codes to indicate command status. You can use these exit codes in scripts and automation workflows to detect failures and take corrective action.

| Exit code | Meaning                                                               |
| --------- | --------------------------------------------------------------------- |
| `0`       | Command completed successfully                                        |
| `1`       | Command failed due to an API, validation, or resource error           |
| `2`       | Invalid command usage, such as missing arguments or unsupported flags |
| `124`     | Command exceeded the configured timeout value                         |

### Collect diagnostic information

When a command fails unexpectedly, enable debug logging to view the underlying API requests and responses.

```bash
harness list pipeline --debug
```

To enable debug logging for an entire shell session:

```bash
export HARNESS_DEBUG=1 
harness list pipeline
```

Debug output includes request URLs, payloads, response status codes, and API error messages, which can help identify the root cause of failures.

#### Debug helpers

The `debug` commands report on the CLI itself rather than on a Harness resource.

```bash
harness debug update_check 
harness debug sso-log 
harness debug miscfg
```

* `harness debug update_check`: Probes the release manifest and reports what an in-place upgrade would do.
* `harness debug sso-log`: Emits SSO auth debug events, which is useful when a browser login flow does not complete.
* `harness debug miscfg`: Triggers a misconfigured command as a registry self-test. This is a development-only helper.

### Authentication issues

#### Unauthorized or invalid token

The API token is expired, revoked, invalid, or does not have permission to access the requested resource.

**Resolution**

{% stepper %}
{% step %}

## Re-authenticate

Re-authenticate using a valid token.
{% endstep %}

{% step %}

## Verify the environment variable

Verify that `HARNESS_API_KEY` contains the expected value if you use environment-variable authentication.
{% endstep %}

{% step %}

## Confirm token permissions

Confirm that the token has permission to access the requested resource.
{% endstep %}
{% endstepper %}

```bash
harness auth login 
harness auth status
```

#### Profile not found

The specified profile does not exist in your local configuration.

**Resolution**

{% stepper %}
{% step %}

## View available profiles

Run `harness auth profiles` to view available profiles.
{% endstep %}

{% step %}

## Verify the selected profile

Verify the value passed through `--profile` or `HARNESS_PROFILE`.
{% endstep %}

{% step %}

## Create a profile if needed

Create a new profile if needed.
{% endstep %}
{% endstepper %}

```bash
harness auth profiles 
harness auth login --profile staging
```

### Scope and context issues

#### Organization or project is required

The command targets a resource that requires organization and project context, but neither was provided through flags, profile defaults, or environment variables.

**Resolution**

Pass the required scope explicitly:

```bash
harness list pipeline --org my-org --project my-project
```

Or configure defaults for your profile:

```bash
harness auth setscope --org my-org --project my-project
```

#### Resource not found

A resource may exist, but the CLI is querying a different account, organization, project, or resource level.

**Resolution**

{% stepper %}
{% step %}

## Verify the organization and project

Verify the organization and project.
{% endstep %}

{% step %}

## Verify the resource level

Verify the resource level using `--level`.
{% endstep %}

{% step %}

## Inspect the request context

Use `--debug` to inspect the request context.
{% endstep %}

{% step %}

## Confirm the resource exists

Confirm the resource exists with a corresponding `list` command.
{% endstep %}
{% endstepper %}

```bash
harness get secret my-secret --level account 
harness get connector shared-github --level org --org platform 

harness list pipeline --org my-org --project my-project
```

### Network issues

#### Connection refused or timeout

The CLI cannot reach the Harness API endpoint. This can occur because of firewall restrictions, VPNs, proxy configuration, or network connectivity issues.

**Resolution**

{% stepper %}
{% step %}

## Verify network connectivity

Verify network connectivity.
{% endstep %}

{% step %}

## Confirm proxy configuration

If your environment uses a proxy, confirm the proxy variables are configured correctly.
{% endstep %}

{% step %}

## Verify the API URL

For self-managed Harness deployments, verify the configured API URL.
{% endstep %}
{% endstepper %}

```bash
export HTTPS_PROXY=http://your-proxy:8080
```

Check the configured API URL:

```bash
echo $HARNESS_API_URL 
harness get account --debug
```

#### TLS handshake failure

The CLI cannot establish a secure connection to the API endpoint. This is typically caused by missing or outdated CA certificates, or by corporate TLS interception.

**Resolution**

{% stepper %}
{% step %}

## Update the certificate store

Update the system certificate store.
{% endstep %}

{% step %}

## Add a custom certificate authority

If your organization uses a custom certificate authority, add it to the system trust store.
{% endstep %}

{% step %}

## Retry the command

Retry the command after updating certificates.
{% endstep %}
{% endstepper %}

### Resource and configuration issues

#### Invalid YAML

The YAML file supplied with `--file` or `-f` contains syntax errors or does not match the expected resource schema.

**Resolution**

Export a known-good resource and compare it with your changes:

```bash
harness get pipeline deploy-prod > current.yaml 
diff current.yaml my-changes.yaml
```

Use `--debug` to inspect API validation errors returned by the server.

#### Unknown command or unknown flag

The command or flag may not exist in your installed CLI version.

**Resolution**

Check your version and upgrade if necessary:

```bash
harness --version 
harness install cli
```

Review available commands:

```bash
harness --help 
harness list noun --matrix
```

### Upgrade issues

#### Configuration migration

After a major CLI upgrade, configuration files may require migration. The CLI attempts to migrate configuration automatically.

**Resolution**

Back up your configuration:

```bash
cp -r ~/.harness ~/.harness.backup
```

Then trigger migration by running any CLI command or re-authenticating:

```bash
harness auth login
```

### Get help

If the issue persists:

* Run `harness <command> --help` to view command-specific usage and flags.
* Re-run the command with `--debug` and capture the output for troubleshooting.
* To confirm that the resource and action are supported, see [Supported resources and actions](/harness-platform/3.0/harness-cli/cli/supported-resources-and-actions.md).
* Contact Harness Support and include relevant error messages, debug output, and CLI version information.

### Related articles

* [Supported resources and actions](/harness-platform/3.0/harness-cli/cli/supported-resources-and-actions.md): Confirm which resources and actions the CLI supports.
* [Global flags and output](/harness-platform/3.0/harness-cli/cli/global-flags-and-output-formats.md): Review shared flags, output formats, and environment variables.
* [Authenticate](/harness-platform/3.0/harness-cli/cli/authenticate-the-harness-cli.md): Review profile and credential configuration.