{"record":{"id":"785c04f3829d733a","repo":"stride3d/stride","slug":"capacity-must-be-a-power-of-two","errorCode":null,"errorMessage":"Capacity must be a power of two","messagePattern":"Capacity must be a power of two","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"error","filePath":"sources/core/Stride.Core/Collections/Dequeue.cs","lineNumber":77,"sourceCode":"    /// </summary>\n    private int offset;\n\n    /// <summary>\n    /// Used to wrap around indices when incrementing outside buffer range\n    /// </summary>\n    private int mask;\n\n    /// <summary>\n    /// Initializes a new instance of the <see cref=\"Deque&lt;T&gt;\"/> class with the specified capacity.\n    /// </summary>\n    /// <param name=\"capacity\">The initial capacity. Must be a power of two greater than <c>0</c>.</param>\n    public Deque(int capacity)\n    {\n        if (capacity < 1)\n            throw new ArgumentOutOfRangeException(nameof(capacity), \"Capacity must be greater than 0.\");\n\n        if (int.IsPow2(capacity) == false)\n            throw new InvalidOperationException(\"Capacity must be a power of two\");\n\n        buffer = new T[capacity];\n        mask = buffer.Length - 1;\n    }\n\n    /// <summary>\n    /// Initializes a new instance of the <see cref=\"Deque&lt;T&gt;\"/> class.\n    /// </summary>\n    public Deque()\n        : this(DefaultCapacity)\n    {\n    }\n\n    #region GenericListImplementations\n\n    /// <summary>\n    /// Gets a value indicating whether this list is read-only. This implementation always returns <c>false</c>.\n    /// </summary>","sourceCodeStart":59,"sourceCodeEnd":95,"githubUrl":"https://github.com/stride3d/stride/blob/96fad776d210c221682aac1ccdf4c79dc046fc38/sources/core/Stride.Core/Collections/Dequeue.cs#L59-L95","documentation":"The same Deque<T> capacity constructor further requires the capacity to be a power of two (1, 2, 4, 8, ...) so that index wrapping can use a bitmask (mask = capacity - 1). When int.IsPow2(capacity) is false it throws InvalidOperationException. Despite the exception type, this is invalid input: capacities like 3, 5, 100 are simply not supported by the ring-buffer layout.","triggerScenarios":"new Deque<T>(100) or any non-power-of-two literal; sizing the deque to an expected item count without rounding up; translating code from List<T>/Queue<T> whose capacity constructors accept arbitrary values.","commonSituations":"Pre-allocating 'expected count' capacities measured empirically (e.g. 100); porting generic queue code to Stride's Deque; configuration values written by hand without the power-of-two constraint in mind.","solutions":["Round up to the next power of two: BitOperations.RoundUpToPowerOf2((uint)capacity).","Use an explicit power-of-two constant (1, 2, 4, 8, 16, ...).","Wrap construction in a helper that validates/normalizes capacity once."],"exampleFix":"// before\nvar deque = new Deque<Entity>(100); // throws: 100 is not a power of two\n\n// after\nvar cap = Math.Max(1, (int)System.Numerics.BitOperations.RoundUpToPowerOf2((uint)100));\nvar deque = new Deque<Entity>(cap); // 128","handlingStrategy":"validation","validationCode":"int capacity = requested < 1 ? 1 : (int)System.Numerics.BitOperations.RoundUpToPowerOf2((uint)requested);\nvar deque = new Deque<Entity>(capacity); // always a valid power of two","typeGuard":null,"tryCatchPattern":"try\n{\n    var deque = new Deque<Entity>(capacity);\n}\ncatch (InvalidOperationException)\n{\n    var deque2 = new Deque<Entity>(System.Numerics.BitOperations.RoundUpToPowerOf2((uint)Math.Max(1, capacity)));\n}","preventionTips":["Always round requested capacities up with BitOperations.RoundUpToPowerOf2.","Remember Deque<T> capacity semantics differ from List<T>/Queue<T>, which accept any value.","Centralize deque construction in one helper that normalizes capacity."],"tags":["csharp","stride-core","collections","argument-validation"],"backgroundTag":"invalid-argument-value","analyzedSha":"96fad776d210c221682aac1ccdf4c79dc046fc38","analyzedAt":"2026-09-14T02:59:31.279Z","contentChangedAt":"2026-09-14T02:59:31.279Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}