Skip to main content

Troubleshooting

Fix common Agents problems by symptom. Start with the Mattermost Server log, filtered by plugin ID mattermost-ai. For request-level detail, turn on trace output in Server Logs mode. See Monitor Agents.

Setup and activation​

SymptomCause and fix
The plugin won't enable and the log says "site URL not configured"Set Site URL under System Console > Environment > Web Server.
The Agents pane asks users to configure an LLMNo service is configured. Add one under System Console > Plugins > Agents. See Configure LLM services.
A self-hosted model returns errors, or the agent never answersThe endpoint might not support the Responses API. For an OpenAI Compatible service, turn Use Responses API off. Also check that the API URL is reachable from the Mattermost Server process and that Default model matches a model the server exposes. See Provider configuration.
A self-hosted model ignores toolsThe model might not support tool calling. Send a direct message that needs a tool and look for a tool call in the reply. If there is none, turn Enable Tools off for that agent. See Verify a self-hosted model.
A self-hosted model keeps calling tools without answeringLower Max tool turns on the agent so it answers sooner, or turn Enable Tools off.
The agent doesn't reply in a direct messageCheck the log for the provider error. Common causes are a wrong API key or model name, a service missing required settings, or an unreachable endpoint. Also check the agent isn't Inactive.
AccessDeniedException, ValidationException, or throttling from BedrockSee Configure Agents with AWS Bedrock.
Saving a service or setting fails with a license messageThe capability needs a higher license level. The message names it. See License requirements.
Requests fail through an HTTP proxyLLM traffic follows HTTP_PROXY and HTTPS_PROXY on the Mattermost Server process. Set them there and restart.

Agents​

SymptomCause and fix
Create agent is disabledThe license's agent cap is full (1 on Free, 3 on Professional). Delete an agent or upgrade.
Create agent is hiddenThe user lacks manage_own_agent and isn't a System Admin.
Edit and Delete are missing for an agentThe user isn't its creator or an agent admin, and lacks manage_others_agent. Migrated v1 agents have no creator, so only System Admins manage them.
An agent shows InactiveHover for the reason: deleted or incomplete service, a service not active on the license, or the agent cap. See Inactive agents.
"This username is already taken"Another user or bot, including a deactivated one, holds it. Pick another name.
The avatar didn't changeThe avatar uploads after the save and can fail alone, for example if it's over 10 MB. Select the image and save again.
A change doesn't show on another cluster nodePropagation takes seconds. If it doesn't arrive, look for "Failed to re-ensure bots after agent update cluster event" or "Failed to publish agent update cluster event" in that node's log, and reload the plugin on it.
A user can't see or use an agentAn access list, a channel restriction, or a service access policy excludes them. See Control who can use agents.
Nobody can use an attribute-based agentIt has no policy, or the access engine is unavailable. An attribute-based agent with no policy denies everyone. Define a policy.

Channels​

SymptomCause and fix
A feature or button is missing, does nothing, or returns a licensing messageCheck License requirements. Channels, summaries, write tools, remote MCP servers, AI search, and meeting summaries each need a license level.
The agent replies but won't use tools in a channelEnable Channel Mention Tool Calling is off. It's off by default. See Control agents in channels.
The Agents channel settings tab is missingIt needs an Enterprise Advanced license, the channel-properties permission, a public or private channel, and at least one agent available in the channel.
Ambient auto-reply stays silentEnable ambient auto-replies is off, the classification said no, or a rate limit applied. See Control agents in channels.
Users can't click links in repliesRender AI-generated links is off, or the domain isn't on the allowlist. See Secure AI-generated links and HTML.

Tools and MCP​

SymptomCause and fix
A tool call fails repeatedlyAfter three failures in a row the agent stops using tools and describes the error. Check API keys and endpoints, MCP connectivity and third-party authorization, and that the user can access the target. Trace output shows tool errors.
Agents have no Mattermost tools after an upgrade from v1, or channel questions fail with "read_channel tool not available"The embedded Mattermost MCP server stays off for a configuration migrated from v1 until it's saved. Open System Console > Plugins > Agents and select Save once. See Upgrade steps.
An agent has no toolsEnable Tools is off, or the MCP grants on its MCPs tab don't include the tool, or an access policy or the user's Tools menu choices removed the server.
A remote server's tool list is emptyFor per-user OAuth servers, the user must connect first. For a service account agent, No service account credentials means the server has no service account headers. Couldn't connect means the headers were rejected. Check that the header value doesn't repeat the header name.
An OAuth authorization fails with a redirect errorRegister the MCP OAuth Callback URL from the Configuration tab in the remote server's OAuth app.
Atlassian shows an authorization errorAn Atlassian organization admin must allow your domain. See Atlassian MCP server.
Users can't connect OAuth servers on mobileMobile can't start MCP OAuth. Use web or desktop.
The agent says it can't find a tool it should haveWith dynamic tool loading, search_tools might not surface it. Add a Retrieval description override on the Tools tab, or turn dynamic loading off for that agent.
External MCP client problemsSee Troubleshooting in the MCP server guide.

Search, summaries, and meetings​

SymptomCause and fix
Channel questions fail with an error about embedded MCP toolsThe built-in read_channel and get_channel_info tools are unavailable to the user. An access policy on the built-in server is the usual cause.
The agent can't read the text of an attached PDF or Office documentThe server must extract document text. Turn on Enable document search by content (FileSettings.ExtractContent) under System Console > Environment > File Storage.
AI search or /ask-channel is unavailableThey need an Enterprise license, and the agent needs the built-in Mattermost tools.
Search results are keyword-onlySemantic search isn't set up, or the index is missing. See Set up semantic search.
Semantic search returns HTTP 503A deferred reindex or a vector index rebuild is running. Search returns when it finishes.
The panel shows Embedding Model ChangedThe provider, model, dimensions, or precision changed. Run a Full Reindex.
A meeting summary failsCheck the server log. The default agent might be inactive or its service unreachable. See Meeting summaries.

HTML artifacts​

SymptomCause and fix
"can only be viewed inside Mattermost"Mattermost is served over plain HTTP, or the artifact URL was opened directly in a tab. Use HTTPS, and open it from the conversation.
"This artifact could not be loaded"The Site URL doesn't match the address users open.
An artifact can still reach the networkThe browser isn't Chromium 152 or later. See Secure AI-generated links and HTML.