LazyTeams

Appearance

Troubleshooting ​

Starting ​

lazyteams can't start without captured tokens.

Tokens not found.

Run ./lazyteams-auth first
to capture tokens automatically.

Run the auth helper once to sign in and capture tokens:

bash
lazyteams-auth

If that still fails, your tokens.env may be empty or incomplete — reset and try again:

bash
lazyteams-auth --clear-session --clear-tokens
lazyteams-auth

Permissions & API errors ​

"HTTP 403: Missing scope permissions on Chat. API requires one of 'Chat.ReadBasic, Chat.Read, Chat.ReadWrite'" ​

You (or your tenant) haven't consented to the Graph permission. Re-check the permission list in Getting Started, open Graph Explorer, sign in with your account, and enable the missing permission.

If a permission shows "Need admin approval", your organization restricts self-service consent — contact your IT administrator.

Other 401 / 403 errors after it worked before ​

Most 401/403 responses are expired tokens. The TUI renews tokens automatically in the background and shows ⟳ Renewing <TOKEN>... in the top bar. If a token can't be renewed automatically (or the top bar shows a renewing state that never finishes), renew it manually:

bash
lazyteams-auth --renew graph    # opens the browser
lazyteams-auth --renew fabric   # opens the browser
lazyteams-auth --renew web      # headless
lazyteams-auth --renew edu      # headless
lazyteams-auth --renew notif    # headless

Note: graph and fabric renewal require a visible browser — they run the Graph Explorer flow. Use --show if you need to see it.

Authentication / login ​

The browser opens but nothing is captured ​

If lazyteams-auth runs headless and captures nothing for ~45 seconds, the saved Microsoft session has expired — Teams never finished loading. The helper detects this and automatically reopens the browser visibly for you to sign in again. If you need to force this:

bash
lazyteams-auth --show

The auth helper seems to hang or capture is incomplete ​

Capture is interactive by nature (it waits for Teams to load and for Graph Explorer). Give it a full 1–2 minutes on the first run. For a clearer picture of what's happening:

bash
lazyteams-auth --show --debug

This forces the browser visible and streams detailed logs to the terminal.

"TEAMS_FABRIC_TOKEN" was not captured ​

The Fabric token is captured by attempting to change your own role in a Private or Shared Channel (see Configuration). If the operation fails because you're the only owner, that's expected — the token is captured on the role-change request anyway.

Files & permissions ​

"tokens.env is readable by other users (mode …)" ​

A warning printed when tokens.env permissions are broader than 0600 (common after restoring from a backup). It's non-fatal. Fix with:

bash
chmod 600 ~/.config/lazyteams/tokens.env

Display issues ​

Odd glyphs / emoji as empty boxes on Windows ​

The standard Windows Command Prompt and PowerShell have limited Unicode/font support. Windows Terminal is strongly recommended. See Platform Support.

The UI renders strangely or colors are wrong ​

Make sure your terminal supports ANSI color and is a modern emulator. If you're using tmux or screen, ensure your terminal is set to xterm-256color.

Debugging & reporting ​

Where are the logs? ​

  • lazyteams --debug enables diagnostic mode in the TUI and propagates --debug to the background auth helper.
  • In debug mode, the auth helper writes detailed logs to ~/.config/lazyteams/auth-helper.log.

Nothing above fixed it — how do I report the bug? ​

Open an issue on GitHub with:

  • The exact error message.
  • What you ran and expected.
  • Your OS and terminal.
  • If relevant, the auth-helper.log contents (redact tokens/cookies first!).

For security issues, do not open a public issue with tokens, cookies, or session data — use a GitHub Security Advisory or a private channel instead (see SECURITY.md).