{"record":{"id":"e919b2b51abfd8c7","repo":"microsoft/semantic-kernel","slug":"the-thread-name-agentstep-threadname-does-not-ha","errorCode":null,"errorMessage":"The thread name {agentStep.ThreadName} does not have a matching thread variable defined.","messagePattern":"The thread name (.+?) does not have a matching thread variable defined\\.","errorType":"exception","errorClass":"KernelException","httpStatus":null,"severity":"error","filePath":"dotnet/src/Experimental/Process.LocalRuntime/LocalProcess.cs","lineNumber":291,"sourceCode":"                    {\n                        ParentProcessId = this.Id,\n                    };\n            }\n            else if (step is KernelProcessProxy proxyStep)\n            {\n                localStep =\n                    new LocalProxy(proxyStep, this._kernel)\n                    {\n                        ParentProcessId = this.RootProcessId,\n                        EventProxy = this.EventProxy,\n                        ExternalMessageChannel = this.ExternalMessageChannel\n                    };\n            }\n            else if (step is KernelProcessAgentStep agentStep)\n            {\n                if (!this._threads.TryGetValue(agentStep.ThreadName, out KernelProcessAgentThread? thread) || thread is null)\n                {\n                    throw new KernelException($\"The thread name {agentStep.ThreadName} does not have a matching thread variable defined.\").Log(this._logger);\n                }\n\n                localStep = new LocalAgentStep(agentStep, this._kernel, thread, this._processStateManager, this.ParentProcessId);\n            }\n            else\n            {\n                // The current step should already have an Id.\n                Verify.NotNull(step.State?.Id);\n\n                localStep =\n                    new LocalStep(step, this._kernel)\n                    {\n                        ParentProcessId = this.Id,\n                        EventProxy = this.EventProxy\n                    };\n            }\n\n            this._steps.Add(localStep);","sourceCodeStart":273,"sourceCodeEnd":309,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/dotnet/src/Experimental/Process.LocalRuntime/LocalProcess.cs#L273-L309","documentation":"Thrown during step initialization when a KernelProcessAgentStep references a ThreadName that does not exist in the process's _threads dictionary. Agent steps require a named thread to manage conversation history; if the thread name on the step doesn't match any entry declared in the process's Threads collection, the step cannot be constructed.","triggerScenarios":"A KernelProcessAgentStep is added to the process with a ThreadName value that has no corresponding key in the process.Threads dictionary. The lookup at line 289 fails and the exception is thrown.","commonSituations":"Typo in the ThreadName property of an agent step versus the key used when adding the thread definition; removing a thread from the process but forgetting to update agent steps that reference it; renaming a thread without updating all agent steps.","solutions":["Ensure every KernelProcessAgentStep.ThreadName exactly matches a key in the process's Threads dictionary.","Search for the ThreadName value shown in the error message across all step definitions to find the mismatch.","Add the missing thread definition to the process's Threads collection, or correct the step's ThreadName to reference an existing thread."],"exampleFix":"// before - step references 'chatThread' but process defines 'assistantThread'\nprocess.AddStep(new KernelProcessAgentStep { ThreadName = \"chatThread\" });\nprocess.Threads[\"assistantThread\"] = new KernelProcessThread(...);\n// after - names match\nprocess.AddStep(new KernelProcessAgentStep { ThreadName = \"assistantThread\" });\nprocess.Threads[\"assistantThread\"] = new KernelProcessThread(...);","handlingStrategy":"validation","validationCode":"// Validate that every agent step's ThreadName exists in the process Threads dictionary before starting\nvar declaredThreadNames = process.Threads.Keys.ToHashSet();\nforeach (var step in process.Steps.OfType<KernelProcessAgentStep>())\n{\n    if (!declaredThreadNames.Contains(step.ThreadName))\n    {\n        throw new InvalidOperationException($\"Agent step '{step.State.Name}' references thread '{step.ThreadName}' which is not declared.\");\n    }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Maintain a single source of truth for thread names and reference it when creating both threads and agent steps.","Run a pre-start validation pass that checks all agent step ThreadName values against the Threads dictionary.","Use constants for thread names to avoid typos."],"tags":["process-framework","agents","threads","configuration"],"backgroundTag":null,"analyzedSha":"c028a0c7dc4f0814cdcbaba9d998f187a41197bf","analyzedAt":"2026-08-13T13:48:05.040Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}