---
title: "Troubleshooting"
description: "Common issues and how to resolve them."
canonical_url: "https://ai-cli.dev/docs/troubleshooting"
---
# Troubleshooting

## Missing API key

```
Error: No API key found
```

Set one of the following environment variables:

```bash
export AI_GATEWAY_API_KEY="your-key"   # recommended — access to all models
export OPENAI_API_KEY="sk-..."         # OpenAI models only
```

Add the export to your shell profile (`~/.zshrc`, `~/.bashrc`) to persist across sessions.

## Invalid model ID

```
Error: model ID must use printable ASCII characters without spaces
```

AI Gateway model IDs are sent as HTTP request metadata and use forms such as `openai/gpt-5.5`. Check the value passed to `--model` and any `AI_CLI_*_MODEL` environment variable for Unicode characters or embedded spaces.

## Timeout errors

Requests are aborted if they exceed the per-command timeout:

| Command            | Timeout     |
| ------------------ | ----------- |
| `text`             | 120 seconds |
| `image`            | 300 seconds |
| `video`            | 300 seconds |
| `audio speak`      | 120 seconds |
| `audio transcribe` | 120 seconds |

Use `--timeout <seconds>` to allow a longer request without changing models. The value must be a positive integer. For example:

```bash
ai image --timeout 600 "a detailed sprite atlas"
```

If you are consistently hitting timeouts, a faster model variant is often the better fix (for example `bytedance/seedance-2.0-fast` instead of `bytedance/seedance-2.0`).

## `--quality` / `--style` warning

```
Warning: --quality and --style only apply to OpenAI models
```

The `--quality` and `--style` flags are OpenAI-specific provider options. They're silently ignored by other providers. Remove these flags when using non-OpenAI image models.

## Version and upgrades

Check your installed version:

```bash
ai --version
```

Upgrade to the latest release:

```bash
npm update -g ai-cli
```

## Gateway unreachable

If the AI Gateway is unreachable, the `models` command will return an empty list and short-name resolution will be unavailable. Use fully-qualified model IDs (`provider/model-name`) to bypass model discovery. Generation commands will still work if you specify the full model ID with `-m`.

Check your network connection and verify the gateway status at [vercel.com/status](https://www.vercel.com/status).

## No output / empty response

If a command exits with code 0 but produces no visible output, it likely wrote to a file. Check stderr for the "Saved to" message, or use `--json` to see structured metadata including the output path:

```bash
ai image "a sunset" --json
```