dotnet/efcore · error · InvalidOperationException

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

Error message

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

What it means

The GetSessionTokenStorage helper in CosmosDatabaseFacadeExtensions resolves the ISessionTokenStorage from the Cosmos provider's CosmosDatabaseWrapper. It throws InvalidOperationException(CosmosNotInUse) when the registered IDatabase service is not a CosmosDatabaseWrapper, meaning the DbContext is not configured with the Cosmos provider. This guard protects Cosmos-specific session-token APIs from being called on a non-Cosmos context.

Solutions

1. Ensure the DbContext is configured with optionsBuilder.UseCosmos(...) before calling session-token extension methods.
2. Guard Cosmos-specific calls with databaseFacade.IsCosmos() before invoking them.
3. Separate Cosmos-specific code paths from generic infrastructure code using provider checks.

Example fix

// before — called without provider guard on any context
context.Database.AppendSessionTokens(tokens);

// after — guard with provider check
if (context.Database.IsCosmos())
{
    context.Database.AppendSessionTokens(tokens);
}

// Check provider before calling Cosmos-specific methods
if (context.Database.IsCosmos())
{
    context.Database.AppendSessionTokens(tokens);
}

When it happens

Trigger: Calling databaseFacade.AppendSessionTokens(tokens) or GetSessionTokenStorage-related methods on a DbContext that uses SQL Server, PostgreSQL, SQLite, or in-memory provider instead of Cosmos. The IDatabase service resolved from the DI container is not a CosmosDatabaseWrapper.

Common situations: Switching providers in a multi-environment setup where dev uses Cosmos but tests use SQLite/InMemory; calling session-token APIs from shared infrastructure code without checking the provider; misconfigured DbContext that is missing the UseCosmos() call in OnConfiguring or AddDbContext.

Related errors

• Specified argument was out of the range of valid values…
• The property ' ' on type ' ' cannot be configured as not…
• The value ' ' provided for argument ' ' must be a valid…
• A call was made to ' ' that changed an option that must be…
• A full-text index is defined for

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

Appendix: 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 3a2006ef56)