What causes "AZURE_OPENAI_ENDPOINT is not set." in microsoft/semantic-kernel?

Set AZURE_OPENAI_ENDPOINT to your Azure OpenAI resource URL (e.g. https://my-resource.cognitiveservices.azure.com/)

microsoft/semantic-kernel · error · InvalidOperationException

AZURE_OPENAI_ENDPOINT is not set.

Error message

AZURE_OPENAI_ENDPOINT is not set.

What it means

The Azure OpenAI Basics migration sample throws InvalidOperationException when AZURE_OPENAI_ENDPOINT is not set. This is the foundational sample comparing SK's ChatCompletionAgent with the Agent Framework's AIAgent for a simple pirate-joke prompt. The endpoint is used with AzureCliCredential to create an AzureOpenAIChatClient.

Source

Thrown at dotnet/samples/AgentFrameworkMigration/AzureOpenAI/Step01_Basics/Program.cs:11

// Copyright (c) Microsoft. All rights reserved.

using Azure.AI.OpenAI;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.Agents;
using Microsoft.SemanticKernel.Connectors.OpenAI;
using OpenAI.Chat;

var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
var deploymentName = System.Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o";
var userInput = "Tell me a joke about a pirate.";

Console.WriteLine($"User Input: {userInput}");

await SKAgent();
await SKAgent_As_AFAgentAsync();
await AFAgent();

async Task SKAgent()
{
    Console.WriteLine("\n=== SK Agent ===\n");

    var builder = Kernel.CreateBuilder().AddAzureOpenAIChatClient(deploymentName, endpoint, new AzureCliCredential());

    var agent = new ChatCompletionAgent()
    {
        Kernel = builder.Build(),

View on GitHub (pinned to c028a0c7dc)

Solutions

Set AZURE_OPENAI_ENDPOINT to your Azure OpenAI resource URL (e.g. https://my-resource.cognitiveservices.azure.com/)
Optionally set AZURE_OPENAI_DEPLOYMENT_NAME (defaults to gpt-4o)
Run az login to ensure AzureCliCredential can acquire a token
Verify the deployment name matches an actual deployment in your Azure OpenAI resource

Example fix

// before
var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");

// after
var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT");
if (string.IsNullOrWhiteSpace(endpoint))
    throw new InvalidOperationException(
        "AZURE_OPENAI_ENDPOINT is not set. " +
        "Set it: export AZURE_OPENAI_ENDPOINT='https://<resource>.cognitivesives.azure.com/'");

Defensive patterns

Strategy: validation

Validate before calling

var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT");
if (string.IsNullOrWhiteSpace(endpoint))
{
    Console.Error.WriteLine("AZURE_OPENAI_ENDPOINT is not set.");
    Console.Error.WriteLine("Example: https://<resource>.cognitiveservices.azure.com/");
    return;
}

Type guard

static bool IsAzureOpenAIEndpointConfigured() =>
    !string.IsNullOrWhiteSpace(Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT"));

Try / catch

try
{
    var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")
        ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
}
catch (InvalidOperationException ex) when (ex.Message.Contains("AZURE_OPENAI_ENDPOINT"))
{
    Console.Error.WriteLine(ex.Message);
    return;
}

Prevention

Set AZURE_OPENAI_ENDPOINT in a shared env-var script sourced before running any AzureOpenAI sample
Verify the endpoint URL matches an existing Azure OpenAI resource in your subscription
Run az login before executing samples that use AzureCliCredential
Add the variable to launchSettings.json for VS debugging

When it happens

Trigger: Running AzureOpenAI/Step01_Basics without AZURE_OPENAI_ENDPOINT in the environment. The throw at line 11 fires before SKAgent(), SKAgent_As_AFAgentAsync(), or AFAgent() execute.

Common situations: First-time setup without reading the README's Environment Variables section; the endpoint was set for a Foundry sample (wrong variable name); az login session expired.

Related errors

AI-assisted analysis of microsoft/semantic-kernel@c028a0c7dc (2026-08-13). Data as JSON: /api/errors/21903dfdf15a6d51. Report an issue: GitHub.