What causes "A subscription key is required" in microsoft/ailab?

Provide a valid Cognitive Services subscription key when constructing AzureAuthToken(key, tokenValue)

microsoft/ailab · error · ArgumentNullException

A subscription key is required

Error message

A subscription key is required

What it means

The AzureAuthToken constructor issues Cognitive Services auth tokens from a subscription key and refuses to run without one. If the key parameter is null or an empty string it throws ArgumentNullException with the message 'A subscription key is required'. Tokens cannot be requested from Azure without a valid key, so the class fails fast in the constructor.

Solutions

Provide a valid Cognitive Services subscription key when constructing AzureAuthToken(key, tokenValue)
Check appsettings.json / configuration for the key entry and that the lookup name matches
Null-check the configured value before constructing the class and surface a clear configuration error
Regenerate/copy the correct key from the Azure portal resource if it was blank

Example fix

// before
var auth = new AzureAuthToken(Configuration["AzureSubKey"], null);
// after
var key = Configuration["AzureSubKey"];
if (string.IsNullOrEmpty(key)) throw new InvalidOperationException("AzureSubKey is missing from configuration");
var auth = new AzureAuthToken(key, null);

Defensive patterns

Strategy: validation

Validate before calling

var key = Configuration["AzureSubKey"];
if (string.IsNullOrEmpty(key))
    throw new InvalidOperationException("AzureSubKey missing from configuration");

Type guard

bool HasSubscriptionKey(string key) => !string.IsNullOrWhiteSpace(key);

Try / catch

try
{
    var auth = new AzureAuthToken(key, tokenValue);
}
catch (ArgumentNullException ex) when (ex.ParamName == "key")
{
    logger.LogError("Subscription key not configured: {Message}", ex.Message);
    throw new InvalidOperationException("Configure the Cognitive Services subscription key", ex);
}

Prevention

Load keys from a strongly-typed configuration class validated at startup
Null-check config values before constructing service clients
Never pass GetSection(...).Value directly without a presence check
Document required config keys and check them with a startup validator

When it happens

Trigger: Instantiating new AzureAuthToken(null, ...) or new AzureAuthToken("", ...) — typically when the key comes from appsettings.json or an environment variable that is missing or empty.

Common situations: Forgetting to add the Speech/Text Analytics subscription key to appsettings.json; key lookup returning empty (GetSection(...).Value is null); leaving the placeholder value empty in config; renaming the config key so the lookup misses.

Related errors

AI-assisted analysis of microsoft/ailab@89fe2fc620 (2026-09-13). Data as JSON: /api/errors/568379dd5b5cdc21. Report an issue: GitHub.

Appendix: source

Thrown at BuildAnIntelligentBot/src/ChatBot/Models/AzureAuthToken.cs:20

namespace ChatBot.Models
{
  /// <summary>
  /// Class with the Cognitive Services Azure Auth Token information.
  /// </summary>
  public class AzureAuthToken
  {
    // When the last valid token was obtained.
    private DateTime _storedTokenTime = DateTime.MinValue;

    // Cache the value of the last valid token obtained from the token service.
    private string _storedTokenValue = string.Empty;

    public AzureAuthToken(string key, string tokenValue)
    {
      if (string.IsNullOrEmpty(key))
      {
        throw new ArgumentNullException("key", "A subscription key is required");
      }

      SubscriptionKey = key;
      StoredTokenValue = tokenValue;
    }

    // Gets the subscription key.
    public string SubscriptionKey { get; private set; }

    public string StoredTokenValue
    {
      get
      {
        return this._storedTokenValue;
      }

      set
      {

View on GitHub (pinned to 89fe2fc620)