dotnet/efcore · error · InvalidOperationException

Cosmos-specific methods can only be used when the context is

Error message

Cosmos-specific methods can only be used when the context is using the Cosmos provider.

What it means

Thrown by GetSessionTokenStorage when the configured IDatabase is not a CosmosDatabaseWrapper. All Cosmos session-token APIs (GetSessionToken, UseSessionToken, AppendSessionToken, etc.) require the Cosmos provider; calling them on a context backed by another provider is a misuse. Fires the moment the extension resolves the Cosmos-specific storage.

Source

Thrown at src/EFCore.Cosmos/Extensions/CosmosDatabaseFacadeExtensions.cs:96

    /// <summary>
    ///     Appends the composite sessions token per container for this <see cref="DbContext" /> with the tokens specified in
    ///     <paramref name="sessionTokens" />.
    /// </summary>
    /// <remarks>See https://aka.ms/efcore-docs-cosmos-session for more information.</remarks>
    /// <param name="databaseFacade">The <see cref="DatabaseFacade" /> for the context.</param>
    /// <param name="sessionTokens">The session tokens to append per container.</param>
    public static void AppendSessionTokens(this DatabaseFacade databaseFacade, IReadOnlyDictionary<string, string> sessionTokens)
    {
        var sessionTokenStorage = GetSessionTokenStorage(databaseFacade);

        sessionTokenStorage.AppendSessionTokens(sessionTokens);
    }

    private static ISessionTokenStorage GetSessionTokenStorage(DatabaseFacade databaseFacade)
    {
        var db = GetService<IDatabase>(databaseFacade);
        return db is not CosmosDatabaseWrapper dbWrapper
            ? throw new InvalidOperationException(CosmosStrings.CosmosNotInUse)
            : dbWrapper.SessionTokenStorage;
    }

    private static TService GetService<TService>(IInfrastructure<IServiceProvider> databaseFacade)
        where TService : class
    {
        var service = databaseFacade.GetService<TService>();
        return service ?? throw new InvalidOperationException(CosmosStrings.CosmosNotInUse);
    }

    /// <summary>
    ///     Gets the configured database name for this <see cref="DbContext" />.
    /// </summary>
    /// <remarks>
    ///     See <see href="https://aka.ms/efcore-docs-cosmos">Accessing Azure Cosmos DB with EF Core</see> for more information and examples.
    /// </remarks>
    /// <param name="databaseFacade">The <see cref="DatabaseFacade" /> for the context.</param>
    /// <returns>The database name.</returns>

View on GitHub (pinned to dbf9771522)

Solutions

1. Only call Cosmos session-token APIs on a context configured with UseCosmos().
2. Guard calls with database.IsCosmos() before invoking session-token methods.
3. Move Cosmos-specific operations behind an interface/provider-strategy so non-Cosmos contexts never reach this code.

Example fix

// before
var token = context.Database.GetSessionToken(); // throws if not Cosmos

// after
if (context.Database.IsCosmos())
{
    var token = context.Database.GetSessionToken();
}

if (!context.Database.IsCosmos())
{
    throw new InvalidOperationException("Session-token APIs require the Cosmos provider.");
}
var token = context.Database.GetSessionToken();

static bool IsCosmosContext(DbContext context)
    => context.Database.ProviderName == "Microsoft.EntityFrameworkCore.Cosmos";

When it happens

Trigger: Calling database.GetSessionToken(), database.UseSessionToken(...), database.AppendSessionToken(...), etc. on a DbContext that was configured with a non-Cosmos provider (SQL Server, SQLite, InMemory, etc.).

Common situations: Sharing an extension method across provider-specific contexts. Switching a context from Cosmos to another provider during refactoring without removing Cosmos-specific calls. Test harnesses using InMemory provider but exercising Cosmos session-token code paths.

Related errors

• The value '{value}' provided for argument '{argumentName}' m
• Unhandled expression '{expression}' of type '{expressionType
• The container with the name '{containerName}' does not exist
• No session token has been set for container: '{container}'.
• Disable automatic session token management using 'options.Se

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