🚨 Slack Error Guide: 'user_not_found' — Fix Bad User Lookups

Overview

The user_not_found error means a Slack method received a user reference it could not resolve to a real user in the workspace the token belongs to. It appears on users.info, users.lookupByEmail, conversations.invite, conversations.open, chat.postMessage (when the “channel” is a user id for a DM), and more. The most frequent cause is passing something other than a canonical Slack user id (U… or W… on Enterprise Grid) — for example a username, an email, a display name, or a stale id from a different workspace.

Slack returns HTTP 200 with ok:false:

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

It occurs whenever the supplied user identifier does not map to a member the calling token can see.

Symptoms

• users.info returns user_not_found for what looks like a valid id.
• users.lookupByEmail fails for a user you know exists (wrong email, or email not shared).
• conversations.invite reports user_not_found for some ids in the batch.
• IDs that worked in one workspace fail in another (Enterprise Grid identity differences).
• Passing a username/@handle or display name instead of the U… id.

Common Root Causes

1. Using a username or display name instead of a user ID

Slack methods require the canonical id (U0123ABCD), never the human handle. Handles are mutable and non-unique.

2. lookupByEmail with the wrong or unshared email

users.lookupByEmail matches the user’s primary Slack email. A typo, an alias, or a workspace that hides email returns user_not_found.

3. Deactivated or deleted users

A deactivated account may resolve differently or be excluded from lookups depending on the method.

4. Cross-workspace / Enterprise Grid identity

On Grid, a person can have a workspace-level id (U…) and an org-level id (W…). An id valid in one workspace isn’t valid in another.

5. Stale cached IDs

A cached id from a departed user or a migrated account no longer resolves.

Diagnostic Workflow

Step 1: Verify the id shape

# Valid user ids start with U (workspace) or W (Enterprise Grid org user)
echo "$USER_ID" | grep -Eq '^[UW][A-Z0-9]{8,}$' && echo "looks valid" || echo "NOT a user id"

NOT a user id

If it fails this check, you are almost certainly passing a handle or email.

Step 2: Resolve an email to an id

curl -s -G "https://slack.com/api/users.lookupByEmail" \
  --data-urlencode "email=jane.doe@example.com" \
  -H "Authorization: Bearer $SLACK_BOT_TOKEN" \
  | jq '{ok, error, id: .user.id, name: .user.name}'

{
  "ok": true,
  "error": null,
  "id": "U04ABCDE12",
  "name": "jane"
}

A user_not_found here means the email doesn’t match any member’s primary Slack email.

Step 3: Confirm the id resolves with users.info

curl -s -G "https://slack.com/api/users.info" \
  --data-urlencode "user=U04ABCDE12" \
  -H "Authorization: Bearer $SLACK_BOT_TOKEN" \
  | jq '{ok, error, deleted: .user.deleted, team: .user.team_id}'

{
  "ok": true,
  "error": null,
  "deleted": false,
  "team": "T03AAAAA1"
}

If deleted is true, the account is deactivated. If team_id differs from your token’s workspace, you have a cross-workspace id.

Step 4: Check which workspace your token is for

curl -s "https://slack.com/api/auth.test" \
  -H "Authorization: Bearer $SLACK_BOT_TOKEN" | jq '{team_id, url}'

{
  "team_id": "T03AAAAA1",
  "url": "https://acme.slack.com/"
}

The user must belong to this team_id for the token to resolve them.

Example Root Cause Analysis

An access-request bot invites approvers to a private channel using ids pulled from a config file. One invite fails:

curl -s -X POST https://slack.com/api/conversations.invite \
  -H "Authorization: Bearer $SLACK_BOT_TOKEN" -H "Content-Type: application/json" \
  -d '{"channel":"C07PRIV0001","users":"U04ABCDE12,U0DEADBEEF"}' | jq .

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

Checking the second id with users.info:

curl -s -G "https://slack.com/api/users.info" --data-urlencode "user=U0DEADBEEF" \
  -H "Authorization: Bearer $SLACK_BOT_TOKEN" | jq .error

"user_not_found"

U0DEADBEEF is a stale id for an employee who left; the config was never updated. The fix is to resolve ids fresh from email at run time (and skip unresolved users) rather than trusting a static id list:

curl -s -G "https://slack.com/api/users.lookupByEmail" \
  --data-urlencode "email=approver@example.com" \
  -H "Authorization: Bearer $SLACK_BOT_TOKEN" | jq -r '.user.id'

U061NEWAPP9

Inviting the freshly-resolved ids succeeds.

Prevention Best Practices

• Always pass canonical user ids (U…/W…), never usernames, @handles, or display names.
• Resolve emails to ids at run time with users.lookupByEmail, and cache with a TTL rather than hardcoding ids.
• Handle deactivated users explicitly (users.info → deleted:true) instead of treating them as errors.
• On Enterprise Grid, be deliberate about workspace (U…) vs org (W…) ids and which the target method expects.
• In batch operations, resolve and validate every id first, and skip/report unresolved users rather than failing the whole batch.
• For ad-hoc triage, the free incident assistant can flag a stale or cross-workspace id. See more in Slack guides.

Quick Command Reference

# Email -> user id
curl -s -G "https://slack.com/api/users.lookupByEmail" \
  --data-urlencode "email=jane.doe@example.com" \
  -H "Authorization: Bearer $SLACK_BOT_TOKEN" | jq '.user.id'

# Validate an id resolves (and isn't deleted)
curl -s -G "https://slack.com/api/users.info" --data-urlencode "user=U04ABCDE12" \
  -H "Authorization: Bearer $SLACK_BOT_TOKEN" | jq '{ok, deleted: .user.deleted}'

# Which workspace is this token for?
curl -s "https://slack.com/api/auth.test" \
  -H "Authorization: Bearer $SLACK_BOT_TOKEN" | jq '.team_id'

Conclusion

user_not_found means Slack could not map your reference to a member of the token’s workspace. The usual root causes:

1. Passing a username/handle/email where a U… id is required.
2. users.lookupByEmail on a wrong, aliased, or hidden email.
3. Deactivated or deleted accounts.
4. Cross-workspace / Enterprise Grid identity mismatches.
5. Stale cached ids for departed or migrated users.

Always use canonical ids, resolve them fresh from email, validate with users.info, and confirm the user belongs to your token’s workspace.