🚨 Slack Error: 'team_not_found' — Cause, Fix, and Troubleshooting Guide

Overview

team_not_found means Slack could not resolve the workspace (team) implied by your request — either the token’s home workspace is gone, or a team_id/team parameter you passed doesn’t map to a real workspace visible to this token.

{
    "ok": false,
    "error": "team_not_found"
}

It shows up on general Web API calls and, more often, on Enterprise Grid / admin methods that take an explicit team_id.

Symptoms

• auth.test fails, or admin methods fail while other calls succeed.
• A hard-coded team_id stopped resolving after an org change.
• Cross-workspace calls on Grid fail for one specific workspace.

Common Root Causes

1. Wrong or stale team_id parameter

Admin/Grid methods take a team_id; a typo or an id from a removed workspace yields team_not_found.

2. The token’s workspace was deleted or migrated

If the workspace behind the token is gone (deleted, or migrated into/out of an org), Slack can’t resolve it.

3. Token not authorised for the target workspace on Grid

An org-level token calling a workspace it isn’t installed on can’t find that team.

How to diagnose

Establish which team the token actually belongs to:

curl -s https://slack.com/api/auth.test \
  -H "Authorization: Bearer $SLACK_BOT_TOKEN"

{"ok": true, "team": "ACME Prod", "team_id": "T0AAAAAAA", "enterprise_id": "E0AAAAAAA"}

Then confirm the team_id you pass to an admin method matches a real workspace:

curl -s "https://slack.com/api/admin.teams.list?limit=100" \
  -H "Authorization: Bearer $SLACK_ORG_TOKEN" | head -c 400

If your target team_id isn’t in the list, it’s wrong or the org token can’t see it.

Fixes

• Use the team_id from auth.test (or admin.teams.list) rather than a hard-coded value.
• Re-pull tokens after any workspace deletion/migration; treat the old ones as dead.
• For Grid admin calls, ensure the org-level token is installed on and authorised for the target workspace.
• Validate the team_id at startup so a wrong id fails loudly on boot, not mid-run.

What to watch out for

• team_not_found (workspace can’t be resolved) is distinct from invalid_auth (token itself is bad) and account_inactive (the app/user is disabled) — check auth.test to tell them apart.
• On Enterprise Grid, workspace ids can change during migrations; don’t hard-code them into automation.
• Store the resolved team_id alongside the token in your secret store so multi-workspace apps always pair the two correctly.

Related

• Slack Error: ‘invalid_auth’
• Slack Error: ‘account_inactive’
• Multi-workspace Slack app OAuth and token storage