Troubleshooting

Use this page when something does not work while you install, build or run MentorAgent. Each section starts from what you see, then gives the cause and the fix.

Find your symptom in this list:

• Install and build: the build cannot find a type of your model provider, the app still runs the old packages, the Azure OpenAI Responses client throws MissingMethodException.
• Startup: the app stops with an InvalidOperationException, the app cannot map the Model Context Protocol (MCP) or Agent-to-Agent (A2A) endpoint.
• Clients and connections: the widget button does nothing, a browser client is blocked by Cross-Origin Resource Sharing (CORS), every request to /mcp answers 500, a client cannot connect to the hub, a confirmation answer gets a 404, restoring a conversation fails.
• What the agent does: it does not call your method, an action with RequiredRoles is always refused, an action runs without a confirmation box, an action that only reads asks for confirmation, a local model ignores the instructions.
• Known issues: the defects of this version, in What's new.

The build stops with error CS0246: the type or namespace OpenAI, AzureOpenAIClient or DefaultAzureCredential could not be found.

Cause. MentorAgent brings no SDK of a model provider. You add the package of your provider, at the version you choose.

Fix. Add the package that your code needs:

With the Responses API of Azure OpenAI, pin the version: see The Azure OpenAI Responses client throws MissingMethodException. If your code uses an Agent Framework hosting package that earlier versions of MentorAgent installed, such as Microsoft.Agents.AI.Hosting.A2A.AspNetCore, add that package to your project yourself.

After the upgrade to 1.0.0, the build succeeds, but the application still behaves like 1.0.0-rc.15.

Cause. A project still references a package with the old ID, which ends with 1.0.0-rc.15. The old and the new packages build side by side without an error, and using lines with the old namespaces keep reaching the old package.

Fix. Follow Move to the Novior.MentorAgent packages. In every project, dotnet list package --include-transitive must list only Novior.MentorAgent packages.

Cause. The widget is on a page or layout that renders statically. It shows its button, but nothing handles the click.

Fix. Make the whole app interactive, with <Routes @rendermode="InteractiveServer" /> in Components/App.razor. Or run the widget on the server: give it its own InteractiveServer render mode in the layout. Place the widget shows both.

The app ends before it listens, with an InvalidOperationException. On a Blazor Server app or a worker, the terminal shows "Hosting failed to start" and the reason. Some hosts stop earlier, at the Map… call, with the same message. This happens when the host maps the endpoints of Novior.MentorAgent.Server: the hub and its HTTP endpoints, the Model Context Protocol (MCP) server, or the Agent-to-Agent (A2A) agent.

In the Quickstart, the key is in user secrets. In the project folder, run dotnet user-secrets list: it must show OpenAI:Key. If it does not, run dotnet user-secrets set OpenAI:Key <your-key> again. The app reads user secrets only in the Development environment. On a server, supply the key another way: see Keys and configuration in the Production checklist.

A .NET MAUI app has no host start to check the options, so the same messages appear the first time MentorAgent is used.

app.MapMentorAgentMcp() or app.MapMentorAgentA2A() stops the app when the server is off or not registered. The message says which. A call to AddMentorAgentMcp() or AddMentorAgentA2A() in the wrong place also stops the app. It stops at the map call or, if the app maps no endpoint, when the host starts.

• AddMentorAgentMcp(), AddMentorAgentA2A() and the MapMentorAgent… methods are in the Novior.MentorAgent.Server package. A Blazor Server app that serves MCP or A2A without the hub must add that package. If the compiler says that WebApplication has no MapMentorAgentMcp, the project does not reference the package.
• AddMentorAgentMcp() called before AddMentorAgent() registers nothing, because it reads the options that AddMentorAgent stores. The app then stops and says so.

MCP server and A2A server show how to turn each one on.

The browser console reports a Cross-Origin Resource Sharing (CORS) error for the request to /mcp. Desktop and IDE clients connect without a problem.

Cause. The /mcp endpoint has no CORS policy. Only browsers check for one, so only a browser-based client is blocked.

Fix. Opt in to a policy. Define a policy named MentorAgentMcp that lists your origins and exposes the Mcp-Session-Id header. You can register it before or after AddMentorAgent:

services.AddCors(options => options.AddPolicy("MentorAgentMcp",
    policy => policy.WithOrigins("https://tools.example.com")
        .AllowAnyHeader()
        .AllowAnyMethod()
        .WithExposedHeaders("Mcp-Session-Id")));

Then call app.UseCors() and require the policy on the endpoint:

app.UseCors();
app.MapMentorAgentMcp(configure: endpoint => endpoint.RequireCors("MentorAgentMcp"));

If you register no policy with that name, MentorAgent registers one that allows any origin. In production, list your own origins. MCP server has the complete configuration. With authentication, Secure the endpoints shows the order of the calls.

Cause. You required a CORS policy on the endpoint, but the app has no CORS middleware. ASP.NET Core refuses to run such an endpoint. The log says that a middleware that supports CORS was not found. A plain MapMentorAgentMcp() does not need the middleware.

Fix. Call app.UseCors() before you map the endpoint, as in A browser client is blocked by CORS. If no browser calls /mcp, remove the RequireCors call instead.

Cause. The client runs on a different origin from the server, for example another port during development, and the browser blocks the SignalR handshake. You do not need CORS when the client is served by the same host.

Fix.

1. On the server, add a CORS policy that lists every client origin and allows credentials.
2. Call UseCors before UseAuthentication() and UseAuthorization(), and write those two calls in Program.cs yourself. If you leave them out, ASP.NET Core adds them before CORS. Then authorization can refuse the browser's preflight request. This is a request that the browser sends before the real request, and it carries no credentials.
3. On the client, use the absolute URL of the hub.

Secure the endpoints and Blazor WebAssembly and Auto show the code.

Your own client answers a confirmation with POST /mentor/approve, and the server replies 404.

Cause. No turn waits for the answer any more. The question was answered already, the user pressed Stop, or the connection that raised it has closed. Closing a connection ends its turn.

Fix. Nothing is wrong. Treat 404 as "nothing left to answer" and close the dialog. 200 means that the waiting turn received the answer. The WebAssembly client of Novior.MentorAgent.Blazor already does this. A 401 or 403 has another cause: the request does not carry the identity of the hub connection. See Secure the endpoints.

POST /mentor/session restores a conversation from a snapshot that GET /mentor/session returned. When it refuses the snapshot, the live conversation stays as it is. The body of the answer says why.

To restore after a restart, or on another instance, persist and share the ASP.NET Core Data Protection key ring ↗ (external site), as you do for authentication cookies. Windows and Azure App Service keep the keys by default. A container without a volume does not.

Without sign-in, the owner check of the snapshot sees every visitor as the same anonymous user, so a snapshot opens for any connection of the application.

Check these in order:

1. The service is registered in dependency injection (DI). If it is not, the log has a warning that the tool was not found in DI, and the method is left out.
2. Its assembly is in ScanAssemblies.
3. The method is public, not static, and declared on the class itself. Inherited methods are ignored. This rule also applies to the classes listed in the Tools of a team member.
4. The method has [MentorAction], or [Description] with a text. A [Description] with an empty text is ignored.
5. The description says what the method is for. The model chooses tools by their name and description, so a vague description is a likely reason for a missed call.
6. Tool filtering did not send the action. With EnableToolFiltering on, the model receives only the actions that match the message. Write each description in the words your users use. The Debug log lists the actions that were sent on each turn.
   • An action that needs confirmation is sent only when its description scores above ToolFilterMinScore.
   • A short answer to a question from the agent, such as "yes, go ahead", carries the actions of the previous message.
7. The action asks for confirmation, and the caller cannot confirm. The MCP server and the A2A agent card do not publish an action that asks for confirmation. Tool filtering does not send such an action when a message matches nothing. A [MentorAction] asks for confirmation by default, unless it declares ReadOnly = true or RequiresConfirmation = false. See RequireConfirmationForWrites.
   • If it only reads, declare ReadOnly = true.
   • If it must run without asking, declare RequiresConfirmation = false.
8. A team member lists the class in Tools. The class is the toolbox of that member only. The coordinator does not call its methods, and the MCP server and the A2A card do not publish them. A line in the log, at Information level, names each such class.
   • Put an action that the coordinator must also offer on a class that no member lists.
   • A [MentorSkill] class keeps its coordinator tools.

Check these causes, one by one:

• Nobody is signed in, or MentorAgent cannot see who is. Anonymous users are refused. When the app has no authentication at all, every user is refused: the app has neither Novior.MentorAgent.Server nor an AuthenticationStateProvider.
• The user does not have the role. MentorAgent checks roles with ClaimsPrincipal.IsInRole (the ClaimTypes.Role claims, by default). With ASP.NET Core Identity, roles reach the claims only when role support is registered: the Blazor template's AddIdentityCore<ApplicationUser>() needs .AddRoles<IdentityRole>().
• The roles are in a roles claim, and the identity does not name that claim. A roles claim works once the identity names it as its RoleClaimType. Microsoft.Identity.Web does this for you. With JwtBearer and MapInboundClaims = false, set TokenValidationParameters.RoleClaimType = "roles". Otherwise IsInRole looks for ClaimTypes.Role, and every action with RequiredRoles stays refused.
• The app is a .NET MAUI Blazor Hybrid app. There is no ASP.NET Core user, so actions with RequiredRoles are refused for everyone until you supply one: see .NET MAUI (Blazor Hybrid).
• Your own AuthenticationStateProvider adds the roles. On the hub, on /mentor/chat and over A2A, MentorAgent reads the user from the request. It does not ask your AuthenticationStateProvider there, so a claim that only it adds is not seen. Add the claim with an IClaimsTransformation. ASP.NET Core applies it to HttpContext.User, and so to the user of the hub connection.
• The caller is an MCP client or another agent. An MCP client sees an action with RequiredRoles only when McpCallerPrincipal returns an authenticated user who holds the role. Other channels withhold gated actions too: see Where nobody can answer.

Cause. A [MentorAction] that is not read-only asks for confirmation by default, unless it declares RequiresConfirmation = false. A method that changes data runs without asking in these cases:

• it declares RequiresConfirmation = false;
• it declares ReadOnly = true, or IsReadOnlyAction returns true for its tool name;
• it is a method with [Description] alone: RequireConfirmationForWrites covers [MentorAction] methods only;
• RequireConfirmationForWrites or RequireConfirmation is false;
• with HitlMode.Native, a rule of AutoApprovalRules approves it.

Fix. Remove the declaration that opts out, or mark the method [MentorAction]. For a method that you cannot annotate, use the RequiresApproval predicate.

MentorAgent also writes a warning to the log the first time it reads your actions. The warning lists the writes that run without confirmation: the [MentorAction] methods that opted out, and the methods with only [Description] that are not declared read-only. See RequireConfirmationForWrites.

With tool filtering on, an action without confirmation can reach the model on any message: see Tool filtering and confirmation.

Cause. A [MentorAction] that declares neither ReadOnly = true nor RequiresConfirmation is treated as an action that changes data. It asks for confirmation, and the MCP server and the A2A card do not publish it.

Fix.

• Declare ReadOnly = true on an action that only reads, or list its tool name in IsReadOnlyAction.
• Declare RequiresConfirmation = false on a write that must run without asking.
• To turn the default off for the whole application, set RequireConfirmationForWrites to false. An action then asks only when it declares RequiresConfirmation = true.

The app builds without a warning. When your code calls GetResponsesClient() on an AzureOpenAIClient, it throws:

System.MissingMethodException: Method not found: 'Void OpenAI.Responses.ResponsesClient..ctor(System.ClientModel.Primitives.ClientPipeline, OpenAI.OpenAIClientOptions)'.

Cause. Azure.AI.OpenAI 2.9.0-beta.1 calls a constructor that OpenAI 2.11 removed. A package that needs OpenAI 2.11 or later brings the newer version: for example a newer Microsoft.Extensions.AI.OpenAI, Microsoft.Agents.AI.OpenAI or Microsoft.Agents.AI.Foundry.

Fix. Keep OpenAI at 2.10. Give each of these references one exact version, built on OpenAI 2.10:

<PackageReference Include="Microsoft.Extensions.AI.OpenAI" Version="[10.6.0]" />
<PackageReference Include="Microsoft.Agents.AI.Foundry" Version="[1.17.0-preview.260804.1]" />

Keep the second line only if you use AIProjectClient or FoundryEvals. The Chat Completions client (GetChatClient), OpenAI direct, and Ollama through its OpenAI-compatible endpoint need no pin. Remove the pin when Azure.AI.OpenAI ships a version built on a newer OpenAI.

Cause: the context window is too short. The context window is the amount of text that the model reads at once. The default window of an Ollama model is shorter than the prompt that MentorAgent builds. Ollama then cuts the start of the prompt, without an error. The model answers without your instructions or tools.

Fix. Create a variant of the model with a larger context, with a Modelfile and ollama create, and use the variant's name as the model name. Ollama and other local models shows the file and the command.

Cause. The model is slow. On a CPU, a long prompt can take minutes.

Fix.

• Raise NetworkTimeout in the OpenAIClientOptions of the client.
• If you turned on EnableSafetyCheck, RequireLookupForRecordQuestions or RequireActionForChangeRequests, raise SafetyCheckTimeout too. These options make an extra model call on each message. This call is the classifier, and SafetyCheckTimeout limits it.
• If the classifier call of RequireLookupForRecordQuestions or RequireActionForChangeRequests times out, the turn runs without that option.
• To make the classifiers faster, point them at a faster model with ClassifierChatClient.

Model providers has the complete Ollama setup.

Also check that the model supports tool calling. MentorAgent needs it to call your methods.

1.0.0 has four known issues. Their causes and workarounds are in Known issues in What's new.