dotnet/AspNetCore.Docs · critical · Exception

Missing base address!

Error message

Missing base address!

What it means

Exception("Missing base address!") thrown inline when constructing the named HttpClient's BaseAddress if builder.Configuration["ExternalApiUri"] is null. The null-coalescing throw ensures the ExternalApi client cannot be registered without a valid base URL, failing at DI registration/startup rather than at first request.

Source

Thrown at aspnetcore/blazor/security/additional-scenarios.md:97

        request.Headers.Authorization =
            new AuthenticationHeaderValue("Bearer", accessToken);

        return await base.SendAsync(request, cancellationToken);
    }
}
```

The token handler is registered and acts as the delegating handler for a named HTTP client in the `Program` file:

```csharp
builder.Services.AddHttpContextAccessor();

builder.Services.AddScoped<TokenHandler>();

builder.Services.AddHttpClient("ExternalApi",
      client => client.BaseAddress = new Uri(builder.Configuration["ExternalApiUri"] ?? 
          throw new Exception("Missing base address!")))
      .AddHttpMessageHandler<TokenHandler>();
```

> [!CAUTION]
> Ensure that tokens are never transmitted and handled by the client (the `.Client` project), for example, in a component that adopts Interactive Auto rendering and is rendered on the client or by a client-side service. Always have the client call the server (project) to process requests with tokens. **Tokens and other authentication data should never leave the server.**
>
> For Interactive Auto components, see <xref:blazor/security/index#secure-data-in-blazor-web-apps-with-interactive-auto-rendering>, which demonstrates how to leave access tokens and other authentication properties on the server. Also, consider adopting the Backend-for-Frontend (BFF) pattern, which adopts a similar call structure and is described in <xref:blazor/security/blazor-web-app-oidc> for OIDC providers and <xref:blazor/security/blazor-web-app-entra> for Microsoft Identity Web with Entra.

## Use a token handler for web API calls

The following approach is aimed at attaching a user's access token to outgoing requests, specifically to make web API calls to external web API apps. The approach is shown for a Blazor Web App that adopts global Interactive Server rendering, but the same general approach applies to Blazor Web Apps that adopt the global Interactive Auto render mode. The important concept to keep in mind is that accessing the <xref:Microsoft.AspNetCore.Http.HttpContext> using <xref:Microsoft.AspNetCore.Http.IHttpContextAccessor> is only performed on the server.

For a demonstration of the guidance in this section, see the `BlazorWebAppOidc` and `BlazorWebAppOidcServer` sample apps (.NET 8 or later) in the [Blazor samples GitHub repository](https://github.com/dotnet/blazor-samples). The samples adopt a global interactive render mode and OIDC authentication with Microsoft Entra without using Entra-specific packages. The samples demonstrate how to pass a JWT access token to call a secure web API.

[Microsoft identity platform](/entra/identity-platform/) with [Microsoft Identity Web packages](/entra/msal/dotnet/microsoft-identity-web/) for [Microsoft Entra ID](https://www.microsoft.com/security/business/microsoft-entra) provides a API to call web APIs from Blazor Web Apps with automatic token management and renewal. For more information, see <xref:blazor/security/blazor-web-app-entra> and the `BlazorWebAppEntra` and `BlazorWebAppEntraBff` sample apps (.NET 9 or later) in the [Blazor samples GitHub repository](https://github.com/dotnet/blazor-samples).

Subclass <xref:System.Net.Http.DelegatingHandler> to attach a user's access token to outgoing requests. The token handler only executes on the server, so using <xref:Microsoft.AspNetCore.Http.HttpContext> is safe.

View on GitHub (pinned to c67a80103a)

Solutions

1. Add "ExternalApiUri": "https://..." to appsettings.json (or the environment-specific appsettings).
2. Set the ExternalApiUri user secret / environment variable in every deployment environment.
3. Validate configuration at startup with a config validator so the failure is clearly attributed.
4. Provide a sensible default for Development and require override only in Production.

Example fix

// before
client.BaseAddress = new Uri(builder.Configuration["ExternalApiUri"] ??
    throw new Exception("Missing base address!"))

// after — validated options with clear message
var externalApiUri = builder.Configuration["ExternalApiUri"]
    ?? throw new InvalidOperationException(
        "Configuration key 'ExternalApiUri' is required. " +
        "Set it in appsettings.json or as an environment variable.");
client.BaseAddress = new Uri(externalApiUri);

var uri = builder.Configuration["ExternalApiUri"];
if (string.IsNullOrWhiteSpace(uri)) {
    throw new InvalidOperationException("Configure 'ExternalApiUri'.");
}

static bool IsValidUri(string? s) => Uri.TryCreate(s, UriKind.Absolute, out _);

try { /* app start */ }
catch (Exception ex) when (ex.Message.Contains("base address"))
{
    host.LogCritical("Missing ExternalApiUri configuration.");
    throw;
}

When it happens

Trigger: ExternalApiUri configuration key is absent from appsettings.json, environment variables, or user secrets when the app starts and AddHttpClient runs the configuration delegate.

Common situations: Missing ExternalApiUri in appsettings/secrets in a new environment; key renamed without updating code (or vice versa); deployment missing the environment variable; local dev without user-secrets configured.

Related errors

• No URI!
• Null EmailAuthKey
• HttpContext not available
• No server address available.
• ${this.type} `template` option must consist of exactly 1 top

AI-assisted analysis of dotnet/AspNetCore.Docs@c67a80103a (2026-08-13). Data as JSON: /api/errors/eaa01c62a7f4c77f. Report an issue: GitHub.