Slack error missing_scope: Token lacks a required OAuth scope

The token is valid and the request is well-formed, but the token was never granted the OAuth scope this method requires. Slack's description: "The token used is not granted the specific scope permissions required to complete this request." It is the most self-diagnosing error on the platform, because the response body goes beyond the string and names names: a needed field lists the scope the method wants, and a provided field lists every scope your token actually carries. Code that logs only error throws that diagnosis away.

The trap is not reading the error — it is what comes after. Scopes are baked into the token at install time. Adding chat:write to your app's scope list under OAuth & Permissions changes what the next issued token will carry; it does nothing to the token your production system already holds. Developers add the scope, see the error persist, and conclude the fix failed. The missing step is reinstalling the app to the workspace, which issues a fresh token containing the new scope, and then deploying that fresh token. Both halves are required: reinstall without updating the stored secret keeps the old token in play, and for internal apps the token string on the OAuth & Permissions page is silently replaced after reinstall.

Two adjacent errors are worth separating. no_permission is about what the token's identity can do in context (typically posting where the bot is not a member), and not_allowed_token_type means the entire class of token is wrong for the method regardless of scopes. If needed already appears inside provided and you still get missing_scope, check that you are sending the token you think you are — bot vs. user token mixups produce exactly that head-scratcher, since bot and user scopes are granted independently.

SDK surfacing is standard: @slack/web-api rejects with ErrorCode.PlatformError and error.data.needed / error.data.provided intact; slack_sdk raises SlackApiError where e.response["needed"] is readable alongside e.response["error"]. Log both fields on every occurrence.

{
  "ok": false,
  "error": "missing_scope",
  "needed": "chat:write",
  "provided": "channels:read,users:read"
}

Decide the app's full scope list before the first install rather than accreting scopes one incident at a time, and write the reinstall-then-rotate-secret procedure into your runbook as a single atomic change. In development, keep a checklist mapping each API method you call to the scope it needs — every method's reference page states it. The scope-vs-membership distinction is walked through in Slack bot not responding.