# How to Troubleshoot NGPT API Key and Configuration Issues: A Complete Guide

> Troubleshoot NGPT API key and configuration issues with our complete guide. Learn to fix common errors by setting environment variables or config files for seamless operation.

- Repository: [nazDridoy/ngpt](https://github.com/nazdridoy/ngpt)
- Tags: how-to-guide
- Published: 2026-03-07

---

**The most common fix for NGPT API key errors is ensuring your `OPENAI_API_KEY` environment variable is exported or your `~/.config/ngpt/ngpt.conf` file contains a valid `"api_key"` field, following the precedence order of Environment → Config File → CLI arguments.**

When working with the `nazdridoy/ngpt` CLI tool, configuration issues typically stem from how the application resolves API credentials across multiple sources. NGPT stores connection details—including the API key, base URL, provider name, and model—in a JSON configuration file while also respecting standard OpenAI-compatible environment variables. Understanding the resolution hierarchy implemented in [`ngpt/core/config.py`](https://github.com/nazdridoy/ngpt/blob/main/ngpt/core/config.py) and the validation logic in [`ngpt/api/client.py`](https://github.com/nazdridoy/ngpt/blob/main/ngpt/api/client.py) is essential for effective troubleshooting.

## Understanding NGPT's Configuration Hierarchy

NGPT resolves configuration values using a strict precedence chain defined in the loading logic at [`ngpt/core/config.py`](https://github.com/nazdridoy/ngpt/blob/main/ngpt/core/config.py) (lines 73-89). The client (`NGPTClient` in [`ngpt/api/client.py`](https://github.com/nazdridoy/ngpt/blob/main/ngpt/api/client.py), lines 9-27) ultimately validates these values before making API requests.

### Configuration File Location and Format

By default, NGPT looks for [`ngpt.conf`](https://github.com/nazdridoy/ngpt/blob/main/ngpt.conf) at `~/.config/ngpt/ngpt.conf` on Linux and macOS. The file contains a JSON array of provider objects:

```json
[
  {
    "api_key": "sk-xxxxxxxxxxxxxxxxxxxx",
    "base_url": "https://api.openai.com/v1/",
    "provider": "OpenAI",
    "model": "gpt-4"
  }
]

```

You can verify the active configuration file path by running `ngpt --show-config`, which prints the resolved path via the `show_config` function in [`ngpt/cli/handlers/api_config_handler.py`](https://github.com/nazdridoy/ngpt/blob/main/ngpt/cli/handlers/api_config_handler.py) (lines 64-66).

### Environment Variable Precedence

Environment variables override config file values. NGPT checks these variables in order of priority:

| Variable | Maps to | Priority |
|----------|---------|----------|
| `OPENAI_API_KEY` | `api_key` | Highest |
| `OPENAI_BASE_URL` | `base_url` | Highest |
| `OPENAI_MODEL` | `model` | Highest |

If you export these variables but NGPT still reports `[Not Set]`, ensure you started a new shell session or sourced your profile (`source ~/.bashrc` or `source ~/.zshrc`).

## Common NGPT API Key Issues and Solutions

### Verify the API Key Is Actually Set

The `NGPTClient.chat` method (lines 57-62 in [`ngpt/api/client.py`](https://github.com/nazdridoy/ngpt/blob/main/ngpt/api/client.py)) explicitly checks if `api_key` is `None`. An empty string is accepted for local endpoints that don't require authentication, but `None` triggers an error.

**Symptoms and fixes:**

- **Error: `API key is not set.`** — The config file lacks an `"api_key"` field and the environment variable is missing. Fix by adding the key to `~/.config/ngpt/ngpt.conf` or exporting `OPENAI_API_KEY`.
- **401 Authentication failed** — The key is present but invalid or expired. Regenerate a valid key from your provider and update the configuration.

### Confirm the Configuration File Is Being Read

If NGPT appears to ignore your settings, verify it is loading the correct file:

1. Run `ngpt --show-config` to see the resolved path and active values.
2. Check the output for `Configuration file: <path>` to confirm the source.
3. If the path is incorrect, either move your file to `~/.config/ngpt/ngpt.conf` or specify a custom location with `--config <path>`.

The configuration loading logic resides in `load_config` within [`ngpt/core/config.py`](https://github.com/nazdridoy/ngpt/blob/main/ngpt/core/config.py).

### Resolve Conflicting Configuration Sources

NGPT applies values in this strict order, with later sources overriding earlier ones:

1. **Environment variables** (`OPENAI_API_KEY`, etc.)
2. **Command-line overrides** (`--api-key`, `--base-url`, `--model`)
3. **Configuration file entry** (selected by `--config-index` or `--provider`)

If you set a value via environment variable but see different behavior, check for CLI overrides that take precedence. Use `ngpt --show-config` (implemented in [`api_config_handler.py`](https://github.com/nazdridoy/ngpt/blob/main/api_config_handler.py), lines 76-94) to inspect the final resolved values.

## Fixing Configuration File Problems

### Pick the Right Configuration Entry

When multiple providers exist in your config file, specify which one to use:

- **By index**: `ngpt --config-index 2 "Your prompt here"` (0-based indexing)
- **By provider name**: `ngpt --provider Gemini "Your prompt here"`

If the provider name is ambiguous, NGPT prompts you to choose via the `handle_config_command` function in [`ngpt/cli/handlers/api_config_handler.py`](https://github.com/nazdridoy/ngpt/blob/main/ngpt/cli/handlers/api_config_handler.py) (lines 13-27). Verify available entries with `ngpt --list-configs`.

### Fix Malformed URLs

The `check_config` function in [`ngpt/core/config.py`](https://github.com/nazdridoy/ngpt/blob/main/ngpt/core/config.py) (lines 84-86) validates that `base_url` starts with `http://` or `https://`. If you see:

```

Warning: Base URL 'myapi.local' doesn't start with http:// or https://

```

Correct the URL by adding the scheme:

```bash
export OPENAI_BASE_URL="http://myapi.local/v1/"

```

Or use the interactive wizard (`ngpt --config`) to re-enter the URL with proper formatting.

### Use the Interactive Configuration Wizard

Running `ngpt --config` without `--config-index` or `--provider` launches an interactive wizard that creates a **new** configuration entry at the end of the file (see `handle_config_command`, lines 94-100 in [`api_config_handler.py`](https://github.com/nazdridoy/ngpt/blob/main/api_config_handler.py)).

The wizard prompts for:

1. **API key** (hidden input to prevent shoulder-surfing)
2. **Base URL** (shows default in brackets)
3. **Provider name** (must be unique; validated via `is_provider_unique` in [`config.py`](https://github.com/nazdridoy/ngpt/blob/main/config.py), lines 164-176)
4. **Model name**

Pressing **Enter** at the API key prompt preserves the existing key, preventing accidental exposure in logs.

### Remove or Edit Stale Configurations

**Removing an entry:**

```bash
ngpt --config --remove --config-index 1

# or

ngpt --config --remove --provider OldService

```

The handler confirms deletion before proceeding (lines 30-84 in [`api_config_handler.py`](https://github.com/nazdridoy/ngpt/blob/main/api_config_handler.py)).

**Editing an entry:**

Provide `--config-index` or `--provider` together with `--config` to modify existing values rather than create new ones. The wizard pre-populates current values; press Enter to keep unchanged fields.

## Code Examples for NGPT Configuration

### Exporting Environment Variables (Recommended for CI/CD)

```bash
export OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxxxxxx"
export OPENAI_BASE_URL="https://api.openai.com/v1/"
export OPENAI_MODEL="gpt-4"

# Now any ngpt command will use these values

ngpt "Summarize the following text …"

```

### Using a Custom Configuration File

```bash

# Place a config file somewhere, e.g. $HOME/.ngpt/custom.conf

cat > $HOME/.ngpt/custom.conf <<EOF
[
  {
    "api_key": "sk-xxxx",
    "base_url": "https://api.openai.com/v1/",
    "provider": "OpenAI",
    "model": "gpt-4"
  }
]
EOF

# Point NGPT at it

ngpt --config $HOME/.ngpt/custom.conf "Explain quantum entanglement"

```

### Selecting a Provider by Name

```bash
ngpt --provider Gemini "Write a haiku about clouds"

```

*(Assumes a configuration entry with `"provider": "Gemini"` exists.)*

### Adding a New Configuration Interactively

```bash
ngpt --config      # launches the wizard, creates a new entry at the end of the file

```

### Removing an Unwanted Configuration

```bash
ngpt --config --remove --provider OldService

# Follow the prompt to confirm deletion

```

## Summary

- **NGPT** stores settings in `~/.config/ngpt/ngpt.conf` (JSON format) and respects `OPENAI_API_KEY`, `OPENAI_BASE_URL`, and `OPENAI_MODEL` environment variables.
- **Precedence order**: Environment variables override CLI arguments, which override configuration file entries.
- **Validation** occurs in [`ngpt/core/config.py`](https://github.com/nazdridoy/ngpt/blob/main/ngpt/core/config.py) (`check_config`) and [`ngpt/api/client.py`](https://github.com/nazdridoy/ngpt/blob/main/ngpt/api/client.py) (`NGPTClient`), rejecting `None` API keys and malformed base URLs.
- **Interactive management** via `ngpt --config` creates new entries, while `ngpt --config --remove` deletes them; use `--config-index` or `--provider` to target specific entries.
- **Quick fixes**: Export environment variables for immediate overrides, verify paths with `ngpt --show-config`, and ensure URLs include `http://` or `https://` schemes.

## Frequently Asked Questions

### Why does NGPT say "API key is not set" when I have it in my config file?

This error originates in [`ngpt/api/client.py`](https://github.com/nazdridoy/ngpt/blob/main/ngpt/api/client.py) when the `api_key` parameter is `None`. This typically happens when NGPT is reading a different configuration file than expected, or when an environment variable is explicitly set to an empty string (which overrides the config file). Run `ngpt --show-config` to verify which file is loaded and whether the key is recognized. If the path is wrong, use `--config <path>` to specify the correct file.

### Can I use NGPT without an API key for local models?

Yes. According to the validation logic in [`ngpt/api/client.py`](https://github.com/nazdridoy/ngpt/blob/main/ngpt/api/client.py) (lines 57-62), an empty string (`""`) is accepted for the API key when connecting to local endpoints that don't require authentication. However, the value cannot be `None`. Ensure your configuration explicitly sets `"api_key": ""` rather than omitting the field entirely, or export `OPENAI_API_KEY=""` to override any existing config values.

### How do I switch between multiple providers quickly?

Use the `--provider` flag to select by the provider name stored in your configuration, or `--config-index` to select by position in the JSON array. For example, `ngpt --provider Gemini "prompt"` targets the entry with `"provider": "Gemini"`, while `ngpt --config-index 1` selects the second entry (0-based indexing). If you frequently switch providers, consider using shell aliases or wrapper scripts that set these flags automatically.

### Why does my base URL warning appear even though the endpoint works?

The `check_config` function in [`ngpt/core/config.py`](https://github.com/nazdridoy/ngpt/blob/main/ngpt/core/config.py) (lines 84-86) validates that `base_url` starts with `http://` or `https://`. If you specify a URL like `localhost:11434` or `myapi.local`, NGPT prints a warning because the scheme is missing. While some local servers may still function, NGPT enforces this validation to prevent ambiguous network requests. Always include the full scheme: `http://localhost:11434/v1/` or `https://api.example.com/v1/`.