Mattermost Troubleshooting
Match the symptom, apply the fix. Most Mattermost API failures come from an empty/expired token, a name used where an ID is required, or a missing System Admin permission.
Login "succeeds" but I have no token
Cause: the session token is in the Token response header, not the JSON body. Reading only the body (curl -s) discards it.
Fix — use -i/-si and extract the header:
MATTERMOST_TOKEN=$(curl -si -X POST "${MATTERMOST_API_URL%/}/api/v4/users/login" \
-H "Content-Type: application/json" \
-d "{\"login_id\":\"${MATTERMOST_ADMIN_USERNAME}\",\"password\":\"${MATTERMOST_ADMIN_PASSWORD}\"}" \
| awk 'tolower($1)=="token:"{print $2}' | tr -d '\r')
If it's still empty, the login itself failed — see below.
Login itself fails (401 on /users/login)
login_id accepts username or email — try the other one.
- Verify
MATTERMOST_API_URL is the server root (e.g. https://mm.example.com), not a URL ending in /api/v4. The skill builds ${MATTERMOST_API_URL%/}/api/v4/users/login.
- If the account has MFA, add
"token":"<6-digit-code>" to the body.
- Repeated failures can trip the login rate limit / account lockout — wait, then retry.
401 Unauthorized (mid-session)
Cause: the session token expired or was revoked (e.g. logout, password change, "revoke all sessions").
- Confirm the header is exactly
Authorization: Bearer ${MATTERMOST_TOKEN} (Bearer, not Token).
- Session tokens expire — just re-run the
setup login to get a fresh one. For unattended use, switch to a personal access token (see api-reference → auth-sessions.md).
- A PAT that suddenly returns
401 has probably expired (v11.9+ lets a PAT carry expires_at; an expired PAT is rejected with 401, like a revoked one). Check the token's metadata with GET /users/{user_id}/tokens (the secret is never returned): a non-zero expires_at that is in the past means expired (it stays listed until the hourly reaper removes it), 0 means no expiry, is_active:false means disabled. Also read the owner's direct messages from the system bot — v11.10+ warns 7, 3 and 1 days before expiry. Fix: POST /users/tokens/rotate (new secret, old one dies immediately) or mint a new PAT with a fresh expires_at. A token created without expires_at has no expiry at all, so a 401 there means it was revoked or disabled (an admin can also bulk-revoke non-compliant tokens, see auth-sessions.md).
- Creating a PAT fails on a server whose admin set
MaximumPersonalAccessTokenLifetimeDays to a non-zero value: the policy requires an expiry within that many days — send expires_at (Unix ms).
403 Forbidden
Cause: authenticated, but the account lacks permission for that action.
- System endpoints (
/config, /system/*, /license, /roles, /ldap, /data_retention, /compliance, /plugins) require the System Admin role. Confirm with GET /users/me → .roles contains system_admin.
- Team/channel actions need the matching team/channel role or a scheme that grants the permission. Check
GET /roles/name/{role_name}.
- A
403 is a real boundary — don't try to route around it; ask the user to use an account with the right role.
404 / "Not found" or "Unable to find the …"
Cause: almost always a name used where a 26-char ID is required (or the object is archived/deleted).
- Resolve first:
GET /teams/name/{name}, GET /teams/{team_id}/channels/name/{channel_name}, GET /users/username/{username}, GET /users/email/{email}.
- Archived teams/channels need
?include_deleted=true on some lookups, or restore them (POST /channels/{id}/restore).
429 Too Many Requests
Cause: rate limiting. Mattermost limits requests per second per session/IP.
- Inspect headers:
curl -s -D - ... | grep -i x-ratelimit. X-Ratelimit-Reset is the UTC epoch when the window resets.
- Back off until reset; add a small
sleep between bulk calls; raise per_page (up to 200) to make fewer requests.
A list seems to be missing rows
Cause: pagination. List endpoints return one page (default 60).
- Walk pages with
?page=0&per_page=200, then page=1, … until a page returns fewer than per_page rows (or empty). page is 0-indexed.
- Some endpoints (channel/post search, threads) wrap results in an object with its own cursor — check the reference file for that resource.
A write returns 400 / "invalid"
- Send
-H "Content-Type: application/json" on any request with a body; omitting it is a common 400 cause.
- Required fields differ per resource — e.g. creating a channel needs
team_id, name, display_name, type. Check the reference file.
- For DMs/GMs the body is a bare JSON array of user ids, not an object.
- Uploads (
/files, /emoji, /plugins, images) are multipart (-F), not JSON.
A post shows my name instead of the custom name/icon (v12.0)
Cause: from Mattermost v12.0 the server silently strips from_webhook, from_bot, from_oauth_app, from_plugin, override_username, override_icon_url, override_icon_emoji and webhook_display_name from props on posts made with a user session or PAT. The post is created, no error is returned, and the author is the authenticating user.
- Fix: post through an incoming webhook (
/hooks/<id> with username/icon_url, allowed when the System Console overrides are enabled — ServiceSettings.EnablePostUsernameOverride / EnablePostIconOverride), a slash command response, or a bot account (posts as the bot). See api-reference → integrations.md.
- On a v11 server the old trick still works — it is going away, do not build new automation on it.
last_viewed_at is -1 (or missing) on channel members (v12.0)
Cause: for other users' memberships the API sanitises last_viewed_at/last_update_at to -1 (read as 1969-12-31). From v12.0 the fields are omitted instead. Your own membership keeps real values (0 = never viewed). Code that reads the -1 sentinel or assumes the field is always present must treat "absent" and -1 the same way. Affects GET /channels/{id}/members[/{user_id}], POST /channels/{id}/members[/ids], GET /users/{id}/teams/{team_id}/channels/members and GET /users/{id}/channel_members.
Optional convenience MCP
If you'd rather call tools than curl for the most common read/post operations, use the official Mattermost MCP server, built into the Mattermost Agents plugin (Mattermost Server v11.2+). Admin: System Console → Plugins → Agents → Model Context Protocol (MCP) → set Enable Mattermost MCP Server (HTTP) to true; endpoint (streamable HTTP, no SSE): ${MATTERMOST_API_URL%/}/plugins/mattermost-ai/mcp-server/mcp; auth: a personal access token as Authorization: Bearer (works without any extra setup) or OAuth 2.0 (an admin must first set Integrations → Integration Management → Enable OAuth 2.0 Service Provider; add Enable OAuth 2.0 Dynamic Client Registration for automatic client registration). It exposes 16 native tools (read_post, read_channel, search_posts, create_post, dm, group_message, create_channel, get_channel_info, get_team_info, search_users, get_channel_members, add_channel_member, get_user_channels, get_team_members, add_team_member, list_agents) plus an extended catalogue loaded on demand through search_tools / load_tool; read-only tools work on every licence level, state-changing tools need Enterprise or above, and every call runs with the calling user's own permissions. Docs: https://docs.mattermost.com/administration-guide/configure/agents-admin-guide.html#mattermost-mcp-server — and the announcement https://mattermost.com/blog/mattermost-mcp-server/. Community servers (kakehashi-inc/mcp-server-mattermost, pvev/mattermost-mcp) also exist.
None of these cover admin, RBAC or integration management — use the REST endpoints in api-reference for those. MCP is not a dependency of this plugin.
1---2name: troubleshoot-353description: Use when a Mattermost REST API call fails or behaves unexpectedly — 401 or 403 mid-session, an expired personal access token, 404 from names used instead of ids, 429 rate limits, missing rows from pagination, 400 on a write, no token after login, or behaviour that changed silently after a server upgrade such as v12 dropping webhook and bot identity props from posts. Maps symptoms to causes and fixes.4metadata:5 source: https://skillmd.com/skills/agents-store/troubleshoot-356---78# Mattermost Troubleshooting910Match the symptom, apply the fix. Most Mattermost API failures come from an empty/expired token, a name used where an ID is required, or a missing System Admin permission.1112## Login "succeeds" but I have no token1314**Cause:** the session token is in the **`Token` response header**, not the JSON body. Reading only the body (`curl -s`) discards it.1516Fix — use `-i`/`-si` and extract the header:17```bash18MATTERMOST_TOKEN=$(curl -si -X POST "${MATTERMOST_API_URL%/}/api/v4/users/login" \19 -H "Content-Type: application/json" \20 -d "{\"login_id\":\"${MATTERMOST_ADMIN_USERNAME}\",\"password\":\"${MATTERMOST_ADMIN_PASSWORD}\"}" \21 | awk 'tolower($1)=="token:"{print $2}' | tr -d '\r')22```23If it's still empty, the login itself failed — see below.2425## Login itself fails (401 on `/users/login`)2627- `login_id` accepts **username or email** — try the other one.28- Verify `MATTERMOST_API_URL` is the server **root** (e.g. `https://mm.example.com`), not a URL ending in `/api/v4`. The skill builds `${MATTERMOST_API_URL%/}/api/v4/users/login`.29- If the account has MFA, add `"token":"<6-digit-code>"` to the body.30- Repeated failures can trip the login rate limit / account lockout — wait, then retry.3132## 401 Unauthorized (mid-session)3334**Cause:** the session token expired or was revoked (e.g. logout, password change, "revoke all sessions").3536- Confirm the header is exactly `Authorization: Bearer ${MATTERMOST_TOKEN}` (Bearer, not `Token`).37- Session tokens expire — just re-run the `setup` login to get a fresh one. For unattended use, switch to a **personal access token** (see `api-reference` → `auth-sessions.md`).38- **A PAT that suddenly returns `401` has probably expired** (v11.9+ lets a PAT carry `expires_at`; an expired PAT is rejected with `401`, like a revoked one). Check the token's metadata with `GET /users/{user_id}/tokens` (the secret is never returned): a non-zero `expires_at` that is in the past means expired (it stays listed until the hourly reaper removes it), `0` means no expiry, `is_active:false` means disabled. Also read the owner's direct messages from the system bot — v11.10+ warns 7, 3 and 1 days before expiry. Fix: `POST /users/tokens/rotate` (new secret, old one dies immediately) or mint a new PAT with a fresh `expires_at`. A token created without `expires_at` has no expiry at all, so a `401` there means it was revoked or disabled (an admin can also bulk-revoke non-compliant tokens, see `auth-sessions.md`).39- Creating a PAT fails on a server whose admin set `MaximumPersonalAccessTokenLifetimeDays` to a non-zero value: the policy requires an expiry within that many days — send `expires_at` (Unix ms).4041## 403 Forbidden4243**Cause:** authenticated, but the account lacks permission for that action.4445- System endpoints (`/config`, `/system/*`, `/license`, `/roles`, `/ldap`, `/data_retention`, `/compliance`, `/plugins`) require the **System Admin** role. Confirm with `GET /users/me` → `.roles` contains `system_admin`.46- Team/channel actions need the matching team/channel role or a scheme that grants the permission. Check `GET /roles/name/{role_name}`.47- A `403` is a real boundary — don't try to route around it; ask the user to use an account with the right role.4849## 404 / "Not found" or "Unable to find the …"5051**Cause:** almost always a **name used where a 26-char ID is required** (or the object is archived/deleted).5253- Resolve first: `GET /teams/name/{name}`, `GET /teams/{team_id}/channels/name/{channel_name}`, `GET /users/username/{username}`, `GET /users/email/{email}`.54- Archived teams/channels need `?include_deleted=true` on some lookups, or restore them (`POST /channels/{id}/restore`).5556## 429 Too Many Requests5758**Cause:** rate limiting. Mattermost limits requests per second per session/IP.5960- Inspect headers: `curl -s -D - ... | grep -i x-ratelimit`. `X-Ratelimit-Reset` is the UTC epoch when the window resets.61- Back off until reset; add a small `sleep` between bulk calls; raise `per_page` (up to 200) to make fewer requests.6263## A list seems to be missing rows6465**Cause:** pagination. List endpoints return one page (default 60).6667- Walk pages with `?page=0&per_page=200`, then `page=1`, … until a page returns fewer than `per_page` rows (or empty). **`page` is 0-indexed.**68- Some endpoints (channel/post search, threads) wrap results in an object with its own cursor — check the reference file for that resource.6970## A write returns 400 / "invalid"7172- Send `-H "Content-Type: application/json"` on any request with a body; omitting it is a common 400 cause.73- Required fields differ per resource — e.g. creating a channel needs `team_id`, `name`, `display_name`, `type`. Check the reference file.74- For DMs/GMs the body is a **bare JSON array of user ids**, not an object.75- Uploads (`/files`, `/emoji`, `/plugins`, images) are **multipart** (`-F`), not JSON.7677## A post shows my name instead of the custom name/icon (v12.0)7879**Cause:** from Mattermost v12.0 the server **silently strips** `from_webhook`, `from_bot`, `from_oauth_app`, `from_plugin`, `override_username`, `override_icon_url`, `override_icon_emoji` and `webhook_display_name` from `props` on posts made with a user session or PAT. The post is created, no error is returned, and the author is the authenticating user.8081- Fix: post through an **incoming webhook** (`/hooks/<id>` with `username`/`icon_url`, allowed when the System Console overrides are enabled — `ServiceSettings.EnablePostUsernameOverride` / `EnablePostIconOverride`), a **slash command response**, or a **bot account** (posts as the bot). See `api-reference` → `integrations.md`.82- On a v11 server the old trick still works — it is going away, do not build new automation on it.8384## `last_viewed_at` is `-1` (or missing) on channel members (v12.0)8586**Cause:** for *other* users' memberships the API sanitises `last_viewed_at`/`last_update_at` to `-1` (read as 1969-12-31). From v12.0 the fields are **omitted** instead. Your own membership keeps real values (`0` = never viewed). Code that reads the `-1` sentinel or assumes the field is always present must treat "absent" and `-1` the same way. Affects `GET /channels/{id}/members[/{user_id}]`, `POST /channels/{id}/members[/ids]`, `GET /users/{id}/teams/{team_id}/channels/members` and `GET /users/{id}/channel_members`.8788## Optional convenience MCP8990If you'd rather call tools than curl for the most common read/post operations, use the **official Mattermost MCP server, built into the Mattermost Agents plugin** (Mattermost Server v11.2+). Admin: System Console → Plugins → Agents → Model Context Protocol (MCP) → set **Enable Mattermost MCP Server (HTTP)** to true; endpoint (streamable HTTP, no SSE): `${MATTERMOST_API_URL%/}/plugins/mattermost-ai/mcp-server/mcp`; auth: a personal access token as `Authorization: Bearer` (works without any extra setup) or OAuth 2.0 (an admin must first set *Integrations → Integration Management → Enable OAuth 2.0 Service Provider*; add *Enable OAuth 2.0 Dynamic Client Registration* for automatic client registration). It exposes 16 native tools (`read_post`, `read_channel`, `search_posts`, `create_post`, `dm`, `group_message`, `create_channel`, `get_channel_info`, `get_team_info`, `search_users`, `get_channel_members`, `add_channel_member`, `get_user_channels`, `get_team_members`, `add_team_member`, `list_agents`) plus an extended catalogue loaded on demand through `search_tools` / `load_tool`; read-only tools work on every licence level, state-changing tools need Enterprise or above, and every call runs with the calling user's own permissions. Docs: https://docs.mattermost.com/administration-guide/configure/agents-admin-guide.html#mattermost-mcp-server — and the announcement https://mattermost.com/blog/mattermost-mcp-server/. Community servers (`kakehashi-inc/mcp-server-mattermost`, `pvev/mattermost-mcp`) also exist.9192None of these cover admin, RBAC or integration management — use the REST endpoints in `api-reference` for those. MCP is not a dependency of this plugin.