microsoft/autogen · error · Exception

Please set OPENAI_API_KEY environment variable.

Error message

Please set OPENAI_API_KEY environment variable.

What it means

Exception thrown in the dotnet README quickstart snippet when the OPENAI_API_KEY environment variable is null. It is a deliberate guard before constructing OpenAIConfig, so the sample fails fast instead of sending an invalid credential to OpenAI.

Source

Thrown at dotnet/README.md:27

You can install both new and old packages from the following feeds:

[![dotnet-ci](https://github.com/microsoft/autogen/actions/workflows/dotnet-build.yml/badge.svg)](https://github.com/microsoft/autogen/actions/workflows/dotnet-build.yml)
[![NuGet version](https://badge.fury.io/nu/AutoGen.Core.svg)](https://badge.fury.io/nu/AutoGen.Core)

> [!NOTE]
> Nightly build is available at:
>
> - [![Static Badge](https://img.shields.io/badge/azure_devops-grey?style=flat)](https://dev.azure.com/AGPublish/AGPublic/_artifacts/feed/AutoGen-Nightly) : <https://pkgs.dev.azure.com/AGPublish/AGPublic/_packaging/AutoGen-Nightly/nuget/v3/index.json>

Firstly, following the [installation guide](./website/articles/Installation.md) to install AutoGen packages.

Then you can start with the following code snippet to create a conversable agent and chat with it.

```csharp
using AutoGen;
using AutoGen.OpenAI;

var openAIKey = Environment.GetEnvironmentVariable("OPENAI_API_KEY") ?? throw new Exception("Please set OPENAI_API_KEY environment variable.");
var gpt35Config = new OpenAIConfig(openAIKey, "gpt-3.5-turbo");

var assistantAgent = new AssistantAgent(
    name: "assistant",
    systemMessage: "You are an assistant that help user to do some tasks.",
    llmConfig: new ConversableAgentConfig
    {
        Temperature = 0,
        ConfigList = [gpt35Config],
    })
    .RegisterPrintMessage(); // register a hook to print message nicely to console

// set human input mode to ALWAYS so that user always provide input
var userProxyAgent = new UserProxyAgent(
    name: "user",
    humanInputMode: HumanInputMode.ALWAYS)
    .RegisterPrintMessage();

View on GitHub (pinned to 027ecf0a37)

Solutions

  1. Export the variable in the shell you run from: export OPENAI_API_KEY=sk-... (or setx / VS Code launchSettings.json environmentVariables on Windows).
  2. Restart the IDE/terminal after setting it so the process picks up the new environment.
  3. For .NET apps, alternatively load it from user-secrets: dotnet user-secrets set "OPENAI_API_KEY" "sk-..." and read configuration instead of the raw environment.
  4. Verify with: echo $OPENAI_API_KEY (or echo %OPENAI_API_KEY% on cmd) before dotnet run.

Example fix

// before
var openAIKey = Environment.GetEnvironmentVariable("OPENAI_API_KEY") ?? throw new Exception("Please set OPENAI_API_KEY environment variable.");

// after (fail fast with a clear message, validated early)
var openAIKey = Environment.GetEnvironmentVariable("OPENAI_API_KEY")
    ?? throw new InvalidOperationException(
        "OPENAI_API_KEY is not set. Run: export OPENAI_API_KEY=<your-key>");
Defensive patterns

Strategy: validation

Validate before calling

if (string.IsNullOrWhiteSpace(Environment.GetEnvironmentVariable("OPENAI_API_KEY")))
{
    Console.Error.WriteLine("Set OPENAI_API_KEY first: export OPENAI_API_KEY=sk-...");
    return;
}

Try / catch

try
{
    var openAIKey = Environment.GetEnvironmentVariable("OPENAI_API_KEY")
        ?? throw new InvalidOperationException("Please set OPENAI_API_KEY environment variable.");
}
catch (InvalidOperationException e) when (e.Message.Contains("OPENAI_API_KEY"))
{
    Console.Error.WriteLine(e.Message);
    Environment.Exit(1);
}

Prevention

When it happens

Trigger: Running the README example without setting OPENAI_API_KEY in the process environment (new shell, dotnet run without env, CI without secrets).

Common situations: Developer copies the snippet into a fresh console app and runs it before exporting the key; env var set in one shell but run in another (IDE/VS Code terminal doesn't inherit); key stored only in appsettings.json or user-secrets instead of the environment.

Related errors

AI-assisted analysis of microsoft/autogen@027ecf0a37 (2026-08-15). Data as JSON: /api/errors/fe2a2d21b48da1f2. Report an issue: GitHub.