Skip to main content

​
Authentication Errors

​
Invalid or Expired Token

Symptom: Commands fail with “authentication failed” or “unauthorized” errors. Solution:
1

Check token validity

Run hc auth status to verify your authentication state.
2

Re-authenticate

If your token is invalid or expired:
hc auth logout
hc auth login
3

Verify credentials

Ensure your API token has the necessary permissions in the Harness platform.
Authentication tokens are stored at $HOME/.harness/auth.json with restricted permissions (0600).

​
Cannot Extract Account ID from Token

Symptom: Error message: “token does not contains accountID” Solution: The CLI expects tokens in the format pat.AccountID.Random.Random. If you’re seeing this error:
  1. Verify your token format is correct
  2. Manually specify the account ID during login: 
    hc auth login --api-token <your-token> --account <account-id>

​
Permission Denied Errors

Symptom: Commands fail with “Access denied” or 403 errors. Causes:
  • Token lacks required permissions for the operation
  • Organization or project scope is incorrect
  • Resource doesn’t exist in the specified scope
Solution: 
# Verify your current context
hc auth status

# Ensure you're using the correct scope
hc registry list --org <org-id> --project <project-id>
Make sure your API token has the appropriate role-based access control (RBAC) permissions for the resources you’re trying to access.

​
Connection Issues

​
Cannot Connect to Harness API

Symptom: Error: “error connecting to Harness API” Possible Causes:
  1. Network connectivity issues
  2. Incorrect API URL
  3. Firewall or proxy blocking the connection
  4. SSL certificate validation issues
Solution:
Test basic connectivity to Harness:
curl -I https://app.harness.io
Verify your API URL is correct:
hc auth status
Default URL should be https://app.harness.io. If using a custom endpoint:
hc auth login --api-url https://your-custom-endpoint.harness.io
If behind a corporate proxy, ensure:
  • HTTPS traffic to *.harness.io is allowed
  • Proxy environment variables are set: 
    export HTTPS_PROXY=http://proxy.company.com:8080
export NO_PROXY=localhost,127.0.0.1

​
Timeout Errors

Symptom: Commands hang or timeout, especially during large operations like migrations. Solution:
  • For registry migrations, adjust concurrency: 
    hc registry migrate --config migrate.yaml --concurrency 5
  • Check network stability and latency to Harness endpoints
  • For large artifact operations, consider splitting into smaller batches

​
Common Command Failures

​
Registry Not Found

Symptom: “not found” error when accessing a registry. Solution:
1

List available registries

hc registry list
2

Verify registry name

Ensure you’re using the correct registry identifier (case-sensitive).
3

Check scope

Registries are scoped to projects. Verify you’re in the correct organization and project:
hc registry list --org <org-id> --project <project-id>

​
Artifact Push Failures

Common Issues:
Error: Operation failed on file pathSolution:
  • Use absolute paths or ensure you’re in the correct directory
  • Verify file permissions allow read access
  • Check the file actually exists: 
    ls -la /path/to/artifact
Error: Validation failed for version fieldSolution: Different package types have different version requirements:
  • Generic: Any string
  • Maven: Follows Maven versioning (e.g., 1.0.0-SNAPSHOT)
  • NPM: Follows semver (e.g., 1.2.3)
  • Docker: Valid tag format
Refer to the specific package type documentation.
Error: Package version already existsSolution:
  • Use the --overwrite flag to replace existing versions (use with caution)
  • Increment the version number
  • Delete the existing version first: 
    hc artifact delete <name> --registry <registry> --version <version>

​
Configuration File Errors

Symptom: “Failed to load configuration” during migration. Solution:
  1. Validate your YAML syntax: 
    # Use a YAML validator
yamllint migrate-config.yaml
  2. Ensure required fields are present:
    • Source registry configuration
    • Destination registry configuration
    • Authentication credentials
  3. Check file permissions allow read access: 
    chmod 644 migrate-config.yaml
See the Registry Migration guide for configuration examples.

​
Command Output Issues

​
JSON Output Parsing Errors

Symptom: Cannot parse JSON output or unexpected format. Solution:
  • Ensure you’re using the --format json flag: 
    hc registry list --format json
  • The default format is table for human-readable output
  • Pipe JSON output to jq for better parsing: 
    hc registry list --format json | jq '.data[] | {name: .identifier, type: .packageType}'

​
Empty or Unexpected Results

Issue: Commands return no results when you expect data. Debugging Steps:
1

Verify scope

Ensure you’re querying the correct organization and project:
hc artifact list --registry <name> --org <org-id> --project <project-id>
2

Check permissions

Verify your token has read access to the resources.
3

Use verbose logging

Enable debug logs to see API responses:
hc registry list --log-file debug.log

​
Build and Installation Issues

​
Building from Source Fails

Symptom: make build fails with compilation errors. Requirements:
  • Go 1.21 or later
  • Required build tools installed
Solution:
1

Install Go

Download and install Go from golang.org
2

Verify Go version

go version
3

Clean and rebuild

make clean
make build
4

Install dependencies

go mod download
go mod verify

​
Binary Not Found After Installation

Symptom: hc: command not found after installation. Solution:
  1. Verify the binary is in your PATH: 
    echo $PATH
  2. Check installation location: 
    which hc
# or
ls -la /usr/local/bin/hc
  3. Add installation directory to PATH: 
    export PATH=$PATH:/usr/local/bin
# Add to ~/.bashrc or ~/.zshrc for persistence
  4. Verify binary permissions: 
    chmod +x /usr/local/bin/hc

​
Getting Help

If you’re still experiencing issues:

Check Logs

Enable logging to diagnose issues:
hc <command> --log-file debug.log

GitHub Issues

Report bugs or request features at: github.com/harness/harness-cli/issues

Community

Join the Harness community for support and discussions.

Documentation

Review the full command reference and guides.
When reporting issues, include:
  • CLI version (hc version if available)
  • Operating system and architecture
  • Full command and error message
  • Relevant log output (with sensitive data redacted)

Build docs developers (and LLMs) love

Get started for freeTalk to us