> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qawolf.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Solutions for common qawolf CLI issues including authentication errors, missing API keys, SDK path problems, and failed flow execution.

## `QAWOLF_API_KEY` is not set

Cause: The CLI could not find an API key in the environment, the system keychain, or the local config file.

Check:

* the `QAWOLF_API_KEY` environment variable is set in the current shell
* credentials have been stored locally with `qawolf auth login`
* the value has not been overwritten by another shell profile

## QA Wolf API rejected the request (HTTP 401)

Cause: The API key is invalid or has been revoked.

Check:

* the key matches one issued for the current workspace
* the key was not truncated or copied with surrounding whitespace
* `qawolf auth whoami` returns the expected workspace

## QA Wolf API rejected the request (HTTP 403)

Cause: The API key is valid but does not have access to the requested environment.

Check:

* the key was issued for a workspace that contains this environment
* the environment ID matches one returned by the platform — see [where to find it](/local-execution/pull-flows#pull-an-environment)

## Could not reach the QA Wolf API

Cause: The CLI could not connect to the platform at `QAWOLF_API_URL`.

Check:

* the network can reach `https://app.qawolf.com` (or the URL configured in `QAWOLF_API_URL`)
* `QAWOLF_API_URL` does not contain a typo or unexpected trailing path
* corporate proxy and VPN settings allow outbound HTTPS

## Flow bundle download link has expired

Cause: The signed URL the CLI received from the platform expired before it downloaded the bundle.

Check:

* re-run `qawolf flows pull --env <env_id>` to fetch a fresh link
* network conditions are not slowing the download past the link's expiration window

## Android SDK not found

Cause: `qawolf install android` could not locate the Android SDK at the path given by `ANDROID_HOME` or `ANDROID_SDK_ROOT`.

Check:

* `ANDROID_HOME` is exported in the current shell and points at the SDK root
* the SDK is installed via Android Studio or via the standalone `cmdline-tools` package
* `sdkmanager` exists at `$ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager`

## iOS targets are not supported

Cause: The selected flow targets an iOS device. The CLI does not yet support iOS execution.

Check:

* the flow's `target` is set to a web or Android value
* iOS flows are filtered out of the run with a pattern argument

## Could not load `@qawolf/testkit`

Cause: The runner could not resolve `@qawolf/testkit` from the project directory.

Check:

* `@qawolf/testkit` is listed in `package.json` and installed
* the command is being run from the project root, or from a directory inside a pulled environment

## Android flows are not supported with `--workers > 1`

Cause: `--workers <n>` was greater than `1` while the run included at least one Android flow.

Check:

* rerun the Android flows with `--workers 1`
* split the run into a web-only invocation with `--workers <n>` and an Android-only invocation with `--workers 1`

## Basic target flow cannot be executed

Cause: The flow targets `"Basic"`, the Node-only platform type. The CLI does not execute Basic flows.

Check:

* the flow has been ported to a supported target, or
* the flow is excluded from the run with a pattern argument