bytebase/bytebase · error

missing the following scopes: %s

Error message

missing the following scopes: %s

What it means

authTest validates that the configured Slack bot token has every OAuth scope the Bytebase webhook integration needs (users:read, users:read.email, channels:manage, groups:write, im:write, chat:write, mpim:write). It collects the scopes present on the token via Slack's auth.test response and, if any required scope is absent, joins the missing list into this error. The message names exactly which scopes must be added to the Slack app.

Source

Thrown at backend/plugin/webhook/slack/app.go:102

		return errors.Wrapf(err, "failed to unmarshal")
	}
	if !res.OK {
		return errors.Errorf("failed to test auth, error: %v", res.Error)
	}

	scopes := resp.Header.Get("x-oauth-scopes")
	hasScope := map[string]bool{}
	for _, s := range strings.Split(scopes, ",") {
		hasScope[s] = true
	}
	var missScope []string
	for _, s := range []string{"users:read", "users:read.email", "channels:manage", "groups:write", "im:write", "chat:write", "mpim:write"} {
		if !hasScope[s] {
			missScope = append(missScope, s)
		}
	}
	if len(missScope) > 0 {
		return errors.Errorf("missing the following scopes: %s", strings.Join(missScope, ","))
	}

	return nil
}

var userIDCache = func() *lru.Cache[string, string] {
	cache, err := lru.New[string, string](5000)
	if err != nil {
		panic(err)
	}
	return cache
}()

// https://api.slack.com/methods/users.lookupByEmail
// id="" indicates that the user is not found.
func (p *provider) lookupByEmail(ctx context.Context, email string) (id string, err error) {
	if id, ok := userIDCache.Get(email); ok {
		return id, nil

View on GitHub (pinned to 1870550677)

Solutions

1. Read the scope list in the error message and add each missing scope in Slack app settings under OAuth & Permissions.
2. Reinstall the app into the workspace so the new scopes are granted to the bot token.
3. Update the bot token (xoxb-...) in the Bytebase webhook configuration and re-run the test.
4. Ensure the token is a bot token, not a legacy or user token.

requiredScopes := []string{"users:read", "users:read.email", "channels:manage", "groups:write", "im:write", "chat:write", "mpim:write"}
// before configuring the webhook, verify the token grants all of them
// via https://slack.com/api/auth.test response scopes (or the app manifest)

if err := provider.Test(ctx, config); err != nil {
	if strings.Contains(err.Error(), "missing the following scopes") {
		// surface the scope list to the admin and prompt for app reinstall
		return fmt.Errorf("slack app needs reinstall with scopes: %w", err)
	}
	return err
}

When it happens

Trigger: The bot token installed on the Slack workspace is missing one or more of the seven required scopes when authTest runs (during webhook provider configuration/testing).

Common situations: Slack app manifest omits scopes like channels:manage or im:write; scopes were changed in the Slack app settings but the app was never reinstalled into the workspace; using a legacy or user token instead of a bot token.

Understand the failure class

Background: "You do not have permission" / 403 Forbidden errors: authenticated but not allowed — causes and fixes across open-source libraries — this error's family across 31 libraries.

Related errors

• auth.sso.no-authorization-endpoint
• FAILED_PRECONDITION
• Failed to store authentication state
• auth.sso.unsupported-provider-type
• auth.sso.invalid-authorization-url

AI-assisted analysis of bytebase/bytebase@1870550677 (2026-09-06). Data as JSON: /api/errors/ecf651cb7a6adf3e. Report an issue: GitHub.