How to debug CLI errors

The openstack CLI communicates with Quake AI APIs over HTTP. When a command fails, the error may originate from your local configuration, network connectivity, authentication, or the remote API. This guide covers how to get verbose output, interpret error messages, and fix the most common issues.

Debug output#

Enable verbose mode#

Add --debug to any command to see the full HTTP request/response cycle:

openstack server list --debug

This prints:

• The HTTP method, URL, and headers sent to the API
• The response status code, headers, and body
• Token generation and caching details

Environment variable#

Set OS_DEBUG=1 to enable debug output for all commands in the current shell:

export OS_DEBUG=1
openstack server list

Reading debug output#

In debug output, look for these key lines:

REQ: curl -g -i -X GET https://compute.us-east-1.rumble.cloud/v2.1/servers ...  # region varies
RESP: [404] ...
RESP BODY: {"itemNotFound": {"code": 404, "message": "Instance ... could not be found."}}

The RESP line gives you the HTTP status code. The RESP BODY contains the error message from the API. Match the status code against the relevant API error reference.

Configuration errors#

Missing or unsourced openrc.sh#

Symptom: Every command fails with a connection or authentication error.

Missing value auth-url required for auth plugin password

Fix: Download and source your openrc.sh file:

source ~/openrc.sh

Verify your environment is configured:

env | grep OS_

You should see OS_AUTH_URL, OS_REGION_NAME, and the app-credential set: OS_AUTH_TYPE=v3applicationcredential, OS_APPLICATION_CREDENTIAL_ID, and OS_APPLICATION_CREDENTIAL_SECRET. Quake AI's generated openrc.sh ships exactly these variables.

Wrong OS_AUTH_URL#

Symptom: Connection refused or SSL errors.

Could not find versioned identity endpoint

Fix: Verify the auth URL is the non-regional Keystone hostname. The correct value is:

https://keystone.rumble.cloud/v3

Check your current value:

echo $OS_AUTH_URL

Conflicting environment variables#

Symptom: Authentication succeeds but commands target the wrong project, or token-based auth overrides credential-based auth.

If OS_TOKEN is set, the CLI uses it directly and ignores OS_APPLICATION_CREDENTIAL_*. This can cause confusing scope mismatches.

Fix: Clear stale variables before sourcing a new openrc:

unset OS_TOKEN OS_AUTH_TOKEN
source ~/openrc.sh

Multiple profiles with clouds.yaml#

If you manage multiple projects, use clouds.yaml instead of environment variables:

clouds:
  production:
    auth:
      auth_url: https://keystone.rumble.cloud/v3
      project_name: my-prod-project
      username: my-user
      user_domain_name: Default
      project_domain_name: Default
    region_name: us-east-1  # us-east-1 | us-east-2 | us-west-1
  staging:
    auth:
      auth_url: https://keystone.rumble.cloud/v3
      project_name: my-staging-project
      username: my-user
      user_domain_name: Default
      project_domain_name: Default
    region_name: us-east-1  # us-east-1 | us-east-2 | us-west-1

Select a profile with OS_CLOUD:

export OS_CLOUD=production
openstack server list

Place clouds.yaml in ~/.config/openstack/ or the current directory.

Interpreting CLI error messages#

The CLI wraps OpenStack API errors in its own format. The meaningful information is at the end of the error output.

Pattern#

<service> <HTTP status>: <API error message>

Example:

Conflict (HTTP 409): Instance 12345 is locked (HTTP 409)

This tells you: the Compute service returned HTTP 409 because the instance is locked. Unlock it with openstack server unlock.

Print the API response directly#

When the CLI error message is unclear, use --debug to see the raw JSON response body. Search for RESP BODY in the debug output.

Network-level failures#

Version and compatibility#

Check installed version#

openstack --version
pip show python-openstackclient

Microversion mismatches#

If a command returns Version X.Y is not supported, the API microversion you requested exceeds what the server supports.

openstack versions show

Quake AI runs OpenStack Antelope (2023.1), supporting Nova microversions 2.1 through 2.95. See API versions and microversions.

Missing service client#

If a command returns '...' is not an openstack command, the service-specific client package may not be installed.

Install the missing client:

pip install python-heatclient

Common errors quick reference#

See also#

• Install OpenStack client: installation and setup
• Authentication and token diagnostics: 401/403 debugging, credential types
• API versions and microversions: version negotiation
• Service endpoints: base URLs for all services
• Error response format: parsing API JSON/XML errors
• Retry and resilience patterns: handling transient failures
• Troubleshooting overview: symptom-first diagnostic guide