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

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 and the validation logic in 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 (lines 73-89). The client (NGPTClient in 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 at ~/.config/ngpt/ngpt.conf on Linux and macOS. The file contains a JSON array of provider objects:

[
  {
    "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 (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) 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.

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, 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 (lines 13-27). Verify available entries with ngpt --list-configs.

Fix Malformed URLs

The check_config function in 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:

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).

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

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).

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)

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

# 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

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

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

Adding a New Configuration Interactively

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

Removing an Unwanted Configuration

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 (check_config) and 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 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 (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 (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/.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}