{"record":{"id":"1a7458cf94f2ccf6","repo":"dotnet/efcore","slug":"the-specified-commandtimeout-value-value-is","errorCode":null,"errorMessage":"The specified 'CommandTimeout' value '{value}' is not valid. It must be a positive number.","messagePattern":"The specified 'CommandTimeout' value '(.+?)' is not valid\\. It must be a positive number\\.","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"error","filePath":"src/EFCore.Relational/Infrastructure/RelationalOptionsExtension.cs","lineNumber":169,"sourceCode":"    }\n\n    /// <summary>\n    ///     The command timeout, or <see langword=\"null\" /> if none has been set.\n    /// </summary>\n    public virtual int? CommandTimeout\n        => _commandTimeout;\n\n    /// <summary>\n    ///     Creates a new instance with all options the same as for this instance, but with the given option changed.\n    ///     It is unusual to call this method directly. Instead use <see cref=\"DbContextOptionsBuilder\" />.\n    /// </summary>\n    /// <param name=\"commandTimeout\">The option to change.</param>\n    /// <returns>A new instance with the option changed.</returns>\n    public virtual RelationalOptionsExtension WithCommandTimeout(int? commandTimeout)\n    {\n        if (commandTimeout is < 0)\n        {\n            throw new InvalidOperationException(RelationalStrings.InvalidCommandTimeout(commandTimeout));\n        }\n\n        var clone = Clone();\n\n        clone._commandTimeout = commandTimeout;\n\n        return clone;\n    }\n\n    /// <summary>\n    ///     The maximum number of statements that will be included in commands sent to the database\n    ///     during <see cref=\"DbContext.SaveChanges()\" /> or <see langword=\"null\" /> if none has been set.\n    /// </summary>\n    public virtual int? MaxBatchSize\n        => _maxBatchSize;\n\n    /// <summary>\n    ///     Creates a new instance with all options the same as for this instance, but with the given option changed.","sourceCodeStart":151,"sourceCodeEnd":187,"githubUrl":"https://github.com/dotnet/efcore/blob/dbf9771522148d61a2467854921bd5dc6f6e6916/src/EFCore.Relational/Infrastructure/RelationalOptionsExtension.cs#L151-L187","documentation":"Thrown by RelationalOptionsExtension.WithCommandTimeout(int?) at line 167-169 when the supplied timeout is a negative integer. EF defines 0 as 'no timeout' and any positive value as seconds; negative values are meaningless. The guard is `commandTimeout is < 0`.","triggerScenarios":"Calling optionsBuilder.UseSqlServer(connStr, sql => sql.CommandTimeout(-1)) or directly setting CommandTimeout to any value less than 0. Also happens when the timeout is read from configuration/appsettings with a misconfigured negative number.","commonSituations":"Reading CommandTimeout from a config file or environment variable that is misconfigured, or passing -1 intending 'infinite' (the correct infinite value is 0 in EF Core). Off-by-one errors in timeout calculation code.","solutions":["Set CommandTimeout to 0 for unlimited/no timeout, or to a positive number of seconds.","Validate the config value before passing it: use Math.Max(0, configuredValue).","Check your appsettings.json / environment variable for a negative timeout value and correct it."],"exampleFix":"// before\noptionsBuilder.UseSqlServer(connStr, sql => sql.CommandTimeout(-1));\n\n// after: 0 means no timeout\noptionsBuilder.UseSqlServer(connStr, sql => sql.CommandTimeout(0));","handlingStrategy":"validation","validationCode":"var timeout = configuration.GetValue<int?>(\"CommandTimeout\") ?? 30;\nif (timeout < 0) throw new ArgumentOutOfRangeException(nameof(timeout), \"CommandTimeout must be >= 0\");\noptionsBuilder.UseSqlServer(connStr, sql => sql.CommandTimeout(timeout));","typeGuard":null,"tryCatchPattern":"// Wrap external configuration reads\ntry { optionsBuilder.UseSqlServer(connStr, sql => sql.CommandTimeout(timeoutFromConfig)); }\ncatch (InvalidOperationException ex) when (ex.Message.Contains(\"CommandTimeout\"))\n{ logger.LogWarning(ex, \"Invalid CommandTimeout in config, falling back to default\"); }","preventionTips":["Validate timeout values from config before passing to EF (>= 0).","Use 0 for infinite timeout, not -1.","Centralize all EF options configuration in one validated helper method."],"tags":["command-timeout","configuration","argument-validation"],"analyzedSha":"dbf9771522148d61a2467854921bd5dc6f6e6916","analyzedAt":"2026-08-06T20:46:03.226Z","schemaVersion":2},"datasetVersion":"2026-08-07T03:17:09.362Z"}