Fixed: System.ArgumentException: Scope 'T' not found in the Microsoft 365 Agents SDK
My Microsoft 365 Agents SDK agent answered every message with Scope 'T' not found the moment it used turnState.Private. The private conversation scope isn't part of the turn state the SDK creates by default, and the error message names a type parameter instead of the missing scope. The fix is to add the scope yourself, with a TurnStateFactory.
What I Was Doing
I was building a small example for a post about private conversation state, on Agents SDK 1.9.205 and .NET 10: an agent that counts each person's messages in each chat. ITurnState, the type of every handler's turnState parameter, has a Private property next to Conversation, User and Temp, so I used it the same way:
using Microsoft.Agents.Builder;
using Microsoft.Agents.Builder.App;
using Microsoft.Agents.Builder.State;
using Microsoft.Agents.Core.Models;
namespace PrivateStateDemo;
public class MessageCounterAgent : AgentApplication
{
public MessageCounterAgent(AgentApplicationOptions options) : base(options)
{
OnActivity(ActivityTypes.Message, CountAsync);
}
private async Task CountAsync(ITurnContext turnContext, ITurnState turnState, CancellationToken cancellationToken)
{
int count = turnState.Private.GetValue<int>("messageCount", () => 0) + 1;
turnState.Private.SetValue("messageCount", count);
string name = turnContext.Activity.From.Name ?? "You";
await turnContext.SendActivityAsync($"{name}, that's message **{count}** from you in this chat.", cancellationToken: cancellationToken);
}
}
Program.cs hosted it the usual way, with MemoryStorage as the agent's storage:
using PrivateStateDemo;
using Microsoft.Agents.Hosting.AspNetCore;
using Microsoft.Agents.Storage;
var builder = WebApplication.CreateBuilder(args);
builder.AddAgentDefaults()
.AddAgent<MessageCounterAgent>();
builder.Services.AddSingleton<IStorage, MemoryStorage>();
var app = builder.Build();
app.UseAgents();
app.MapDefaultAgentEndpoints();
app.Run();
It built without a warning. I ran it with dotnet run and sent hello from the Microsoft 365 Agents Playground.
What I Expected
Alex Wilber, that's message 1 from you in this chat. Alex Wilber is the Playground's made-up user.
What I Got
The agent answered with an error message instead:

The agent's terminal had the exception, logged by the adapter:
fail: Microsoft.Agents.Hosting.AspNetCore.CloudAdapter[0]
Unhandled exception during turn processing. Scope 'T' not found
=====================================
ErrorCode: -2147024809
Source: Microsoft.Agents.Builder
Method: GetScope
TimeStamp: 2026-11-21T12:03:11.0397880Z
Error: Scope 'T' not found
HelpLink Url: Not Provided
=====================================
System.ArgumentException: Scope 'T' not found
at Microsoft.Agents.Builder.State.TurnState.GetScope[T]()
at Microsoft.Agents.Builder.State.TurnState.get_Private()
at PrivateStateDemo.MessageCounterAgent.CountAsync(ITurnContext turnContext, ITurnState turnState, CancellationToken cancellationToken) in /Users/you/source/PrivateStateDemo/MessageCounterAgent.cs:line 17

The message doesn't say which scope is missing. There's no scope called T anywhere in my code.
What I Checked
The stack trace. The exception starts inside the SDK, in TurnState.get_Private(), the getter of the Private property I called on line 17, which calls TurnState.GetScope<T>(). So the turn state didn't have the scope that Private looks for.
Which scopes a turn state starts with. In the SDK's source at version 1.9.205, the constructor of TurnState that takes a storage adds three scopes, then any extra ones you pass in (TurnState.cs, lines 43 to 53):
public TurnState(IStorage storage, params IAgentState[] agentStates)
{
_scopes.Add(ConversationState.ScopeName, new ConversationState(storage));
_scopes.Add(UserState.ScopeName, new UserState(storage));
_scopes.Add(TempState.ScopeName, new TempState());
foreach (var agentState in agentStates)
{
_scopes[agentState.Name] = agentState;
}
}
Conversation, user and temp. No private conversation scope. Microsoft's API reference for this constructor says the same: it creates AgentStateSet with default ConversationState and UserState, and its agentStates parameter is an additional list of AgentState objects to manage.
Which turn state my agent gets. The SDK builds a turn state at the start of every turn by calling AgentApplicationOptions.TurnStateFactory. The API reference describes the delegate: TurnState for an Agent is created at the beginning of a Turn by invoking the specified factory delegate. When the options come from dependency injection, as they do with AddAgent<T>(), the SDK sets that factory to a plain new TurnState(storage) (AgentApplicationOptions.cs, line 156): the three default scopes.
Where the 'T' comes from. GetScope<T>() throws when no scope of the type T is registered (TurnState.cs, lines 93 to 100):
public T GetScope<T>()
{
if (TryGetScope<T>(out var scope))
{
return scope;
}
throw new ArgumentException($"Scope '{nameof(T)}' not found");
}
C#'s nameof(T) gives the name of the type parameter as written in the code, which is the letter T, not the type it stands for. So the message is the same Scope 'T' not found whichever scope is missing.
Why It Happens
ITurnState.Private is there on every turn state, but the scope behind it only exists if something adds it. The turn state the SDK creates for you has the conversation, user and temp scopes, so the first use of turnState.Private throws, and the exception's message can't tell you which scope it was looking for.
The Fix
Give the agent a TurnStateFactory that adds a PrivateConversationState to the default scopes. AddAgent<T>() registers AgentApplicationOptions only when you haven't registered them yourself (ServiceCollectionExtensions.cs, line 78), so you can register options of your own in Program.cs, before AddAgent:
using Microsoft.Agents.Builder;
using Microsoft.Agents.Builder.App;
using Microsoft.Agents.Builder.State;
using Microsoft.Agents.Hosting.AspNetCore;
using Microsoft.Agents.Storage;
using PrivateStateDemo;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddSingleton<IStorage, MemoryStorage>();
builder.Services.AddSingleton(sp =>
{
IStorage storage = sp.GetRequiredService<IStorage>();
return new AgentApplicationOptions(sp, sp.GetRequiredService<IConfiguration>(), sp.GetRequiredService<IChannelAdapter>(), storage)
{
TurnStateFactory = () => new TurnState(storage, new PrivateConversationState(storage))
};
});
builder.AddAgentDefaults()
.AddAgent<MessageCounterAgent>();
var app = builder.Build();
app.UseAgents();
app.MapDefaultAgentEndpoints();
app.Run();
new AgentApplicationOptions(sp, configuration, adapter, storage)is the constructor the SDK uses when it registers the options itself, so everything it reads from configuration and from the app's services is still set up.TurnStateFactory = () => new TurnState(storage, new PrivateConversationState(storage))creates the three default scopes, plus a private conversation scope, all in the same storage. The SDK calls it at the start of every turn.MessageCounterAgent.csdoesn't change.turnState.Privatenow finds its scope.
After the Fix
I built the agent again, ran it, and sent hello and how are you?:

The count goes up, and the terminal has no exception left.
Common Mistakes
| Mistake | What happens | Do this instead |
|---|---|---|
Using turnState.Private with the default turn state | Scope 'T' not found on the first message | Add PrivateConversationState in a TurnStateFactory |
Creating the options with new AgentApplicationOptions(storage) | The settings the SDK reads from configuration and from the app's services are left out | Use the constructor that takes the service provider |
| Giving the private scope a different storage | Its values are kept apart from the conversation's and the user's | Pass the same IStorage to every scope |
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
Scope 'T' not found | A scope your code uses isn't in the turn state | Add it in your TurnStateFactory |
| The error stays after you added the factory | The agent still gets options without your factory | Check that your AddSingleton for AgentApplicationOptions is in the Program.cs of the project you run |
FAQ
Why doesn't the SDK add the private scope by default?
Neither the SDK's source nor its documentation says. What adding it changes: the SDK loads every scope in the turn state at the start of each turn, so a private scope means one more storage read per turn, and one more stored record for each person in each conversation.
Can I add a scope of my own the same way?
Yes. A scope is a class derived from AgentState with its own storage key, and you pass an instance to the TurnState constructor, as with PrivateConversationState here. Your handlers then read it with turnState.GetScope<YourScope>().
Does the same error appear for other scopes?
Yes, with the same message: GetScope<T>() always says 'T'. When you see it, check which scope the line in the stack trace asks for.
Conclusion
Scope 'T' not found means a turn state was asked for a scope it doesn't have, and the 'T' is the name of a type parameter, not of your scope. With turnState.Private, the missing scope is the private conversation scope, which the SDK's default turn state leaves out. Register AgentApplicationOptions with a TurnStateFactory that adds PrivateConversationState, and the private scope works like the others.
Additional Resources
- TurnStateFactory delegate — how the SDK creates a turn state at the start of every turn.
- TurnState constructors — the default scopes, and the extra ones you can pass in.
- PrivateConversationState class — the private conversation scope.
- Manage state — state scopes and storage in the Agents SDK.
