Skip to main content

Common Errors

Start with:

teams auth doctor --output json
teams auth status --output json
teams config show --output json

Common error codes include AUTH_FAILED, AUTH_TOKEN_EXPIRED, PERMISSION_DENIED, RATE_LIMITED, CONFIG_ERROR, and KEYRING_ERROR.

See error codes.

PERMISSION_DENIED with an empty message​

Microsoft Graph often answers an under-permissioned request with 403 and an empty message, which on its own says nothing about what is missing. The CLI appends a Hint: naming the permissions the token actually carries — its delegated scopes, or its application roles when the token is app-only:

Permission denied: Microsoft Graph returned 403 with no message
Hint: this token carries the delegated scopes: Presence.Read.All User.Read. If the one this
operation needs is not in that list, run `teams auth doctor` to see what the profile resolves to,
then `teams auth login` to consent to it.

Compare that list against the permission the operation needs in the permissions matrix. An application role cannot be added by signing in again — it is granted on the app registration and consented by an administrator, and the hint says so. An opaque (non-JWT) token yields no claims and gets no hint.

Failed to parse API response​

This means Graph returned a response the CLI could not deserialize — the HTTP call itself succeeded. The message now carries what the parser objected to and where:

API error (200): Failed to parse API response: error decoding response body:
invalid type: map, expected a string at line 1 column 66

That usually indicates a mismatch between a Graph response shape and the CLI's model, which is worth reporting with the message quoted in full.

Stored token is incomplete​

Windows only. The token is stored across several Credential Manager entries, and one of them is missing — typically after an interrupted write. Sign in again:

teams auth login

See token caching for how the entries are laid out.

A chat attachment opens with "you don't have permission"​

A file sent with message send --chat … --attach is uploaded to your own OneDrive, where the other members of the chat have no access by default. From v0.7.0 the CLI grants them read access after each upload, the way the Teams client does. If it cannot — the warning on stderr names the member and the reason — or if the file was sent by an older release, share it from OneDrive by hand: open the Microsoft Teams Chat Files folder, pick the file, and grant the members read access. Sharing needs Files.ReadWrite, the same scope as the upload. See Message Attachments.

A background job hangs, or says "Not authenticated", after an upgrade on macOS​

macOS grants Keychain access to one specific binary. After brew upgrade or a rebuild, the new teams must be approved again. An interactive shell shows the prompt, but a daemon or scheduled job cannot answer it and waits, or reads no token at all. Approve the new binary once in a terminal, or run the unattended process with TEAMS_CLI_TOKEN_STORE=file and sign in once with it set. Tokens then live in 0600 files and no Keychain prompt is involved. See Token Caching.

A debug build from source (cargo build) keeps its tokens and config under the separate storage namespace teams-cli-dev from v0.9.0, so it never touches the installed release's items. Sign in once with that build; its "Not authenticated" message names the namespace, and teams --version shows it.

auth login keeps signing in through a customer app​

From v0.9.0 a delegated login saves --client-id and --tenant-id to the profile, and later logins reuse them. The login's stderr line says saved in profile '<name>' when that happens. To return the profile to the OSO app, delete its client_id and tenant_id lines from the config file (teams config path shows where), or set them to null with teams config set. See Multi-Tenant Profiles.

message delete fails with "Requested API is not supported"​

Versions before v0.8.0 sent the HTTP DELETE verb, which Microsoft Graph does not support on messages, so message delete never worked. v0.8.0 uses the softDelete action, adds message undelete, and requires --yes. Deleting a channel message also needs the admin-consented ChannelMessage.ReadWrite scope.