dotnet/efcore · error · InvalidOperationException

Disable automatic session token management using 'options.Se

Error message

Disable automatic session token management using 'options.SessionTokenManagementMode' to use this method.

What it means

Thrown by the private SessionTokenStorage.CheckMode guard, which runs at the start of every manual session-token method (SetSessionTokens, AppendSessionTokens, AppendDefaultContainerSessionToken, SetDefaultContainerSessionToken, GetTrackedTokens, GetDefaultContainerTrackedToken). When the mode is FullyAutomatic, manual management is disabled by design and any attempt to use these methods is rejected.

Source

Thrown at src/EFCore.Cosmos/Storage/Internal/SessionTokenStorage.cs:214

    /// <summary>
    ///     This is an internal API that supports the Entity Framework Core infrastructure and not subject to
    ///     the same compatibility standards as public APIs. It may be changed or removed without notice in
    ///     any release. You should only use it directly in your code with extreme caution and knowing that
    ///     doing so can result in application failures when updating to a new Entity Framework Core release.
    /// </summary>
    public virtual void Clear()
    {
        foreach (var key in _containerSessionTokens.Keys)
        {
            _containerSessionTokens[key] = new CompositeSessionToken(_defaultToken);
        }
    }

    private void CheckMode()
    {
        if (_mode == SessionTokenManagementMode.FullyAutomatic)
        {
            throw new InvalidOperationException(CosmosStrings.EnableManualSessionTokenManagement);
        }
    }

    private sealed class CompositeSessionToken
    {
        private string? _string;
        private bool _isChanged;
        private readonly HashSet<string> _tokens = [];

        public CompositeSessionToken(string? token, bool isSet = false)
        {
            if (token != null)
            {
                Add(token);
            }

            IsSet = isSet;
        }

View on GitHub (pinned to dbf9771522)

Solutions

1. Remove the manual session-token calls; in FullyAutomatic mode the provider tracks tokens itself.
2. Switch to Manual or SemiAutomatic if you need to control tokens programmatically.
3. Gate manual calls behind a mode check so they only run when not FullyAutomatic.

Example fix

// before - mode is FullyAutomatic but code calls manual API
optionsBuilder.UseCosmos(..., o => o.SessionTokenManagementMode(SessionTokenManagementMode.FullyAutomatic));
storage.SetSessionTokens(tokens); // throws

// after - either remove the call (FullyAutomatic manages tokens)
// or switch mode
optionsBuilder.UseCosmos(..., o => o.SessionTokenManagementMode(SessionTokenManagementMode.Manual));
storage.SetSessionTokens(tokens);

// Only call manual APIs when not in FullyAutomatic mode.
if (mode != SessionTokenManagementMode.FullyAutomatic)
{
    storage.SetSessionTokens(tokens);
}

try { storage.SetSessionTokens(tokens); }
catch (InvalidOperationException ex) when (ex.Message.Contains("Disable automatic session token management"))
{
    // switch mode to Manual or stop calling manual APIs
}

When it happens

Trigger: Setting options.SessionTokenManagementMode to FullyAutomatic and then invoking any manual session-token API on the internal SessionTokenStorage. The provider owns token management in FullyAutomatic mode, so caller interference is forbidden.

Common situations: Copy-pasting manual token-management code from a SemiAutomatic/Manual codebase into a context configured for FullyAutomatic. Library code that unconditionally calls SetSessionTokens regardless of the configured mode. Misunderstanding that FullyAutomatic means 'do not touch tokens yourself'.

Related errors

• Cosmos-specific methods can only be used when the context is
• The container with the name '{containerName}' does not exist
• No session token has been set for container: '{container}'.
• The value '{value}' provided for argument '{argumentName}' m
• The time to live for analytical store was configured to '{tt

AI-assisted analysis of dotnet/efcore@dbf9771522 (2026-08-06). Data as JSON: /api/errors/db808ea6e55cb694. Report an issue: GitHub.