Ctrlk
Sign UpGet a DemoContact Us
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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

Quick troubleshooting workflow

When a command fails unexpectedly:

  1. Re-run the command with --debug.

  2. Verify authentication with harness auth status.

  3. Confirm the correct organization, project, and resource level.

  4. Verify that the resource exists using the corresponding list command.

  5. Check your CLI version with harness --version.

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.

To enable debug logging for an entire shell session:

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.

  • 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

  1. Re-authenticate using a valid token.

  2. Verify that HARNESS_API_KEY contains the expected value if you use environment-variable authentication.

  3. Confirm that the token has permission to access the requested resource.

Profile not found

The specified profile does not exist in your local configuration.

Resolution

  1. Run harness auth profiles to view available profiles.

  2. Verify the value passed through --profile or HARNESS_PROFILE.

  3. Create a new profile if needed.

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:

Or configure defaults for your profile:

Resource not found

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

Resolution

  1. Verify the organization and project.

  2. Verify the resource level using --level.

  3. Use --debug to inspect the request context.

  4. Confirm the resource exists with a corresponding list command.

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

  1. Verify network connectivity.

  2. If your environment uses a proxy, confirm the proxy variables are configured correctly.

  3. For self-managed Harness deployments, verify the configured API URL.

Check the configured API URL:

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

  1. Update the system certificate store.

  2. If your organization uses a custom certificate authority, add it to the system trust store.

  3. Retry the command after updating certificates.

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:

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:

Review available commands:

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:

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

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.

  • Contact Harness Support and include relevant error messages, debug output, and CLI version information.

Related articles

PreviousWorker Agents
NextOverview

Last updated

Was this helpful?