# How to debug CLI errors

Source: https://docs.quake.ai/docs/tools/cli-debugging
Markdown: https://docs.quake.ai/docs/tools/cli-debugging.md

---

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

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

```bash
export OS_DEBUG=1
openstack server list
```

### Reading debug output

In debug output, look for these key lines:

```text
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](/reference/compute/api-errors).

## Configuration errors

### Missing or unsourced openrc.sh

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

```text
Missing value auth-url required for auth plugin password
```

**Fix:** Download and source your `openrc.sh` file:

```bash
source ~/openrc.sh
```

Verify your environment is configured:

```bash
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](/docs/tools/generate-app-credentials) ships exactly these variables.

### Wrong OS_AUTH_URL

**Symptom:** Connection refused or SSL errors.

```text
Could not find versioned identity endpoint
```

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

```text
https://keystone.rumble.cloud/v3
```

Check your current value:

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

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

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

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

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

**Example:**

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

| Symptom | Likely cause | Fix |
|---|---|---|
| `Connection refused` | Wrong endpoint URL, or VPN not connected | Verify `OS_AUTH_URL`. Check VPN/network connectivity: `curl -s $OS_AUTH_URL` |
| `Connection timed out` | Firewall blocking the port, or endpoint unreachable | Check firewall rules. Try from a different network. |
| `SSL: CERTIFICATE_VERIFY_FAILED` | Missing CA bundle, self-signed cert, or corporate proxy intercepting TLS | Set `OS_CACERT=/path/to/ca-bundle.crt` or (not recommended) `--insecure` |
| `Name or service not known` | DNS resolution failure | Check DNS: `nslookup keystone.rumble.cloud` |

## Version and compatibility

### Check installed version

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

```bash
openstack versions show
```

Quake AI runs OpenStack Antelope (2023.1), supporting Nova microversions 2.1 through 2.95. See [API versions and microversions](/docs/tools/api-versions).

### Missing service client

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

| Command prefix | Required package |
|---|---|
| `openstack stack ...` | `python-heatclient` |
| `openstack coe ...` | `python-magnumclient` |

Install the missing client:

```bash
pip install python-heatclient
```

## Common errors quick reference

| Error | Cause | Fix |
|---|---|---|
| `Missing value auth-url required for auth plugin password` | `openrc.sh` not sourced | `source ~/openrc.sh` |
| `The request you have made requires authentication (HTTP 401)` | Token expired | Re-source openrc or run `openstack token issue` |
| `Policy doesn't allow ... to be performed (HTTP 403)` | Role not authorized for this action | Check project role assignment. See [auth diagnostics](/docs/operate/troubleshooting/auth-token-diagnostics). |
| `No valid host was found (HTTP 500)` | Insufficient capacity for the requested flavor | Try a different flavor or availability zone |
| `Quota exceeded for resources (HTTP 403/413)` | Project quota full | `openstack quota show --usage`. See [quota troubleshooting](/docs/operate/troubleshooting/quota-and-limits). |
| `Instance ... is locked (HTTP 409)` | Instance is locked against accidental changes | `openstack server unlock YOUR_INSTANCE` |
| `Could not find any suitable endpoint` | Wrong region or missing service in catalog | Check `OS_REGION_NAME`. Run `openstack catalog list`. |
| `'stack list' is not an openstack command` | Missing `python-heatclient` | `pip install python-heatclient` |
| `Connection refused` | Wrong endpoint or network issue | Verify `OS_AUTH_URL`. Test: `curl -s $OS_AUTH_URL` |
| `Version X.Y is not supported` | Microversion too high | Remove `--os-compute-api-version` or set to `2.1` |

## See also

- [Install OpenStack client](/docs/tools/install-openstack-client): installation and setup
- [Authentication and token diagnostics](/docs/operate/troubleshooting/auth-token-diagnostics): 401/403 debugging, credential types
- [API versions and microversions](/docs/tools/api-versions): version negotiation
- [Service endpoints](/docs/tools/service-endpoints): base URLs for all services
- [Error response format](/reference/api-conventions/error-response-format): parsing API JSON/XML errors
- [Retry and resilience patterns](/reference/api-conventions/retry-and-resilience): handling transient failures
- [Troubleshooting overview](/docs/operate/troubleshooting): symptom-first diagnostic guide