{"record":{"id":"da2f1c9b047ab447","repo":"dotnet/efcore","slug":"specified-argument-was-out-of-the-range-of-valid-v","errorCode":null,"errorMessage":"Specified argument was out of the range of valid values. (Parameter 'connectionMode')","messagePattern":"Specified argument was out of the range of valid values\\. \\(Parameter 'connectionMode'\\)","errorType":"validation","errorClass":"ArgumentOutOfRangeException","httpStatus":null,"severity":"error","filePath":"src/EFCore.Cosmos/Infrastructure/Internal/CosmosDbOptionExtension.cs","lineNumber":323,"sourceCode":"    ///     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 ConnectionMode? ConnectionMode\n        => _connectionMode;\n\n    /// <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 CosmosOptionsExtension WithConnectionMode(ConnectionMode connectionMode)\n    {\n        if (!Enum.IsDefined(typeof(ConnectionMode), connectionMode))\n        {\n            throw new ArgumentOutOfRangeException(nameof(connectionMode));\n        }\n\n        var clone = Clone();\n\n        clone._connectionMode = connectionMode;\n\n        return clone;\n    }\n\n    /// <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 IWebProxy? WebProxy\n        => _webProxy;\n","sourceCodeStart":305,"sourceCodeEnd":341,"githubUrl":"https://github.com/dotnet/efcore/blob/3a2006ef569de08368d59db5e1468aa8f407e4f8/src/EFCore.Cosmos/Infrastructure/Internal/CosmosDbOptionExtension.cs#L305-L341","documentation":"CosmosOptionsExtension.WithConnectionMode throws ArgumentOutOfRangeException(nameof(connectionMode)) when the supplied Microsoft.Azure.Cosmos.ConnectionMode value is not a defined member of the ConnectionMode enum. The guard uses Enum.IsDefined(typeof(ConnectionMode), connectionMode). It catches garbage produced by an unsafe int->enum cast (e.g. (ConnectionMode)999) before it reaches the Cosmos SDK where the failure would be more obscure.","triggerScenarios":"Casting an arbitrary integer to ConnectionMode and passing it: options.WithConnectionMode((ConnectionMode)cfg.Value); reading the mode from configuration as int and casting without validation; downgrading the Azure Cosmos SDK where a ConnectionMode member was removed so a serialized value no longer maps to a defined member.","commonSituations":"Loading ConnectionMode from a settings file as int and casting directly; reflection-based configuration that bypasses compile-time enum checks; SDK version skew between the configured value and the loaded Azure.Cosmos assembly.","solutions":["Validate the value with Enum.IsDefined(typeof(ConnectionMode), value) before casting; fall back to Gateway or Direct if it is not defined.","Bind configuration as a named string and parse with Enum.TryParse<ConnectionMode>(name, out var mode).","Use the strongly typed ConnectionMode member (ConnectionMode.Direct or ConnectionMode.Gateway) at the call site rather than integer casts.","If you are not sure which modes are valid for your SDK version, enumerate Enum.GetNames<ConnectionMode>() and log them at startup."],"exampleFix":"// before - throws for any int that is not Gateway(0)/Direct(1)/Gateway(1) per SDK\nvar mode = (ConnectionMode)configuration.GetValue<int>(\"Cosmos:ConnectionMode\");\noptions.WithConnectionMode(mode);\n\n// after - parse by name with a safe default\nvar name = configuration.GetValue<string>(\"Cosmos:ConnectionMode\");\nvar mode = Enum.TryParse<ConnectionMode>(name, ignoreCase: true, out var m)\n    ? m\n    : ConnectionMode.Gateway;\noptions.WithConnectionMode(mode);","handlingStrategy":"validation","validationCode":"// Validate before passing to WithConnectionMode.\nstatic ConnectionMode SafeConnectionMode(int raw, ConnectionMode fallback = ConnectionMode.Gateway)\n    => Enum.IsDefined(typeof(ConnectionMode), raw) ? (ConnectionMode)raw : fallback;","typeGuard":"static bool IsValid(ConnectionMode mode) => Enum.IsDefined(typeof(ConnectionMode), mode);","tryCatchPattern":null,"preventionTips":["Bind ConnectionMode from configuration by name (Enum.TryParse), not by int cast.","Use the typed member (ConnectionMode.Direct / Gateway) at call sites where possible.","After upgrading the Azure Cosmos SDK, re-check the defined ConnectionMode members.","Wrap every int->ConnectionMode cast in a SafeConnectionMode helper."],"tags":["ef-core","cosmos","validation","enum","configuration"],"backgroundTag":null,"analyzedSha":"3a2006ef569de08368d59db5e1468aa8f407e4f8","analyzedAt":"2026-08-11T23:42:04.146Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}