{"record":{"id":"f48b120e9198b0ec","repo":"microsoft/FASTER","slug":"unable-to-affinitize-thread","errorCode":null,"errorMessage":"Unable to affinitize thread","messagePattern":"Unable to affinitize thread","errorType":"exception","errorClass":"FasterException","httpStatus":null,"severity":"error","filePath":"cs/src/core/Utilities/Native32.cs","lineNumber":238,"sourceCode":"        {\n            uint nrOfProcessors = GetActiveProcessorCount(ALL_PROCESSOR_GROUPS);\n            ushort nrOfProcessorGroups = GetActiveProcessorGroupCount();\n            uint nrOfProcsPerGroup = nrOfProcessors / nrOfProcessorGroups;\n\n            GROUP_AFFINITY groupAffinityThread = default(GROUP_AFFINITY);\n            GROUP_AFFINITY oldAffinityThread = default(GROUP_AFFINITY);\n\n            IntPtr thread = GetCurrentThread();\n            GetThreadGroupAffinity(thread, ref groupAffinityThread);\n\n            threadIdx = threadIdx % nrOfProcessors;\n\n            groupAffinityThread.Mask = (ulong)1L << ((int)(threadIdx % (int)nrOfProcsPerGroup));\n            groupAffinityThread.Group = (uint)(threadIdx / nrOfProcsPerGroup);\n\n            if (SetThreadGroupAffinity(thread, ref groupAffinityThread, ref oldAffinityThread) == 0)\n            {\n                throw new FasterException(\"Unable to affinitize thread\");\n            }\n        }\n\n        /// <summary>\n        /// Get number of groups (sockets) and processors per group\n        /// </summary>\n        /// <returns></returns>\n        public static (uint numGroups, uint numProcsPerGroup) GetNumGroupsProcsPerGroup()\n        {\n            uint nrOfProcessors = GetActiveProcessorCount(ALL_PROCESSOR_GROUPS);\n            ushort nrOfProcessorGroups = GetActiveProcessorGroupCount();\n            uint nrOfProcsPerGroup = nrOfProcessors / nrOfProcessorGroups;\n            return (nrOfProcessorGroups, nrOfProcsPerGroup);\n        }\n\n        /// <summary>\n        /// Accepts thread id = 0, 1, 2, ... and sprays them round-robin\n        /// across all cores (viewed as a flat space). On NUMA machines,","sourceCodeStart":220,"sourceCodeEnd":256,"githubUrl":"https://github.com/microsoft/FASTER/blob/321d872eabda6a0345c8bd76419f89723ed864ae/cs/src/core/Utilities/Native32.cs#L220-L256","documentation":"FasterException thrown by Native32.AffinitizeThreadRoundRobin when the Win32 SetThreadGroupAffinity call returns 0 (failure). The library uses this during epoch/thread affinitization to pin threads across processor groups; if the OS refuses the affinity mask, the setup fails fast.","triggerScenarios":"Calling AffinitizeThreadRoundRobin (used by FasterLog/FASTER server or TickAffinitize setup) on Windows when the requested threadIdx maps to a group/mask the OS rejects — e.g. mask 1 << (threadIdx % procsPerGroup) exceeding available processors in the group, or insufficient privileges (restricted job objects, containers, VMs with limited CPU groups).","commonSituations":"Running in Windows containers or constrained VMs where thread affinity is not permitted; launching more threads than logical processors; running on systems with multiple processor groups where group math mismatches; using non-Windows where this P/Invoke path is unsupported.","solutions":["Run on hardware/VM where the thread count does not exceed available logical processors per group","Avoid thread affinitization (do not enable affinity options) in containers or restricted environments","Verify the process has permission to set thread affinity (not restricted by Job Object policies)","Confirm processor group layout with GetActiveProcessorGroupCount/GetActiveProcessorCount and align threadIdx"],"exampleFix":"// before\nfor (int i = 0; i < 128; i++)\n    Native32.AffinitizeThreadRoundRobin((uint)i, threadHandles[i]);\n// after\nint procs = Environment.ProcessorCount;\nfor (int i = 0; i < Math.Min(128, procs); i++)\n    Native32.AffinitizeThreadRoundRobin((uint)i, threadHandles[i]);","handlingStrategy":"try-catch","validationCode":"if (OperatingSystem.IsWindows() && threadIdx < Environment.ProcessorCount && CanSetThreadAffinity()) { ... }","typeGuard":null,"tryCatchPattern":"try { Native32.AffinitizeThreadRoundRobin(idx, thread); }\ncatch (FasterException ex) when (ex.Message == \"Unable to affinitize thread\")\n{ logger.Warn(\"Affinity not permitted; continuing without pinning\"); }","preventionTips":["Do not enable thread affinitization in containers, job-restricted or shared VMs","Keep thread count <= Environment.ProcessorCount","Only use affinity options on Windows with known processor-group layout"],"tags":["windows","threading","native-interop","cpu-affinity"],"backgroundTag":"unsupported-platform","analyzedSha":"321d872eabda6a0345c8bd76419f89723ed864ae","analyzedAt":"2026-09-15T22:18:00.693Z","contentChangedAt":"2026-09-15T22:18:00.693Z","schemaVersion":2},"datasetVersion":"2026-09-23T02:17:17.105Z"}