{"record":{"id":"db808ea6e55cb694","repo":"dotnet/efcore","slug":"disable-automatic-session-token-management-using","errorCode":null,"errorMessage":"Disable automatic session token management using 'options.SessionTokenManagementMode' to use this method.","messagePattern":"Disable automatic session token management using 'options\\.SessionTokenManagementMode' to use this method\\.","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"error","filePath":"src/EFCore.Cosmos/Storage/Internal/SessionTokenStorage.cs","lineNumber":214,"sourceCode":"    /// <summary>\n    ///     This is an internal API that supports the Entity Framework Core infrastructure and not subject to\n    ///     the same compatibility standards as public APIs. It may be changed or removed without notice in\n    ///     any release. You should only use it directly in your code with extreme caution and knowing that\n    ///     doing so can result in application failures when updating to a new Entity Framework Core release.\n    /// </summary>\n    public virtual void Clear()\n    {\n        foreach (var key in _containerSessionTokens.Keys)\n        {\n            _containerSessionTokens[key] = new CompositeSessionToken(_defaultToken);\n        }\n    }\n\n    private void CheckMode()\n    {\n        if (_mode == SessionTokenManagementMode.FullyAutomatic)\n        {\n            throw new InvalidOperationException(CosmosStrings.EnableManualSessionTokenManagement);\n        }\n    }\n\n    private sealed class CompositeSessionToken\n    {\n        private string? _string;\n        private bool _isChanged;\n        private readonly HashSet<string> _tokens = [];\n\n        public CompositeSessionToken(string? token, bool isSet = false)\n        {\n            if (token != null)\n            {\n                Add(token);\n            }\n\n            IsSet = isSet;\n        }","sourceCodeStart":196,"sourceCodeEnd":232,"githubUrl":"https://github.com/dotnet/efcore/blob/dbf9771522148d61a2467854921bd5dc6f6e6916/src/EFCore.Cosmos/Storage/Internal/SessionTokenStorage.cs#L196-L232","documentation":"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.","triggerScenarios":"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.","commonSituations":"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'.","solutions":["Remove the manual session-token calls; in FullyAutomatic mode the provider tracks tokens itself.","Switch to Manual or SemiAutomatic if you need to control tokens programmatically.","Gate manual calls behind a mode check so they only run when not FullyAutomatic."],"exampleFix":"// before - mode is FullyAutomatic but code calls manual API\noptionsBuilder.UseCosmos(..., o => o.SessionTokenManagementMode(SessionTokenManagementMode.FullyAutomatic));\nstorage.SetSessionTokens(tokens); // throws\n\n// after - either remove the call (FullyAutomatic manages tokens)\n// or switch mode\noptionsBuilder.UseCosmos(..., o => o.SessionTokenManagementMode(SessionTokenManagementMode.Manual));\nstorage.SetSessionTokens(tokens);","handlingStrategy":"validation","validationCode":"// Only call manual APIs when not in FullyAutomatic mode.\nif (mode != SessionTokenManagementMode.FullyAutomatic)\n{\n    storage.SetSessionTokens(tokens);\n}","typeGuard":null,"tryCatchPattern":"try { storage.SetSessionTokens(tokens); }\ncatch (InvalidOperationException ex) when (ex.Message.Contains(\"Disable automatic session token management\"))\n{\n    // switch mode to Manual or stop calling manual APIs\n}","preventionTips":["Decide on one session-token mode per context and document it.","Do not copy manual token-management code into FullyAutomatic contexts.","Gate manual calls behind a mode check."],"tags":["cosmos","session-token","configuration","mode-mismatch"],"analyzedSha":"dbf9771522148d61a2467854921bd5dc6f6e6916","analyzedAt":"2026-08-06T20:46:03.226Z","schemaVersion":2},"datasetVersion":"2026-08-07T02:17:10.218Z"}