Troubleshooting

Find the message you see, then follow the fix. Messages from email-tool also reach your assistant, which can tell you the same.

Setup

You see	Fix
uvx: command not found	Install uv, then close and reopen the terminal.
The email tools do not appear in a desktop app on macOS	The app cannot find uvx. Use its full path from which uvx in the app's settings, as shown in Advanced setup.
The email tools do not appear in normal ChatGPT Chat	Local tools work in ChatGPT's Work and Codex modes. Normal Chat does not reach them yet.
No mailbox is configured.	Ask your assistant to "add my mailbox" (Start here).
No setup page opens when you ask to add a mailbox	Your app may not open pages itself: your assistant then shows a link. Open that link.
This setup page has closed	It closes after one mailbox or 10 minutes. Ask your assistant to add a mailbox again.
You already have a mailbox called ..., for ...	That name belongs to another address. Leave the name blank or choose another.
A sign-in is already open in another tab	Finish the sign-in in the other tab, or close this page and ask again.
No mailbox called 'x'. Configured: ...	Use one of the names listed, or add that mailbox.
Several mailboxes are configured; name one of: ...	Tell the assistant which mailbox to use.

Passwords and App Passwords

You see	Fix
No password for mailbox 'work' on this machine.	Run email-tool-mcp add work again.
The login check fails for a Gmail address	Gmail needs an App Password, not your account password.
App Passwords is missing from your Google account	Your organization turned them off. Use Google Workspace.
The login check fails for any other mailbox	Check the server names and ports with email-tool-mcp list. IMAP uses port 993. SMTP uses STARTTLS on ports 25 and 587 and direct TLS on other ports (usually 465). Then ask your provider whether IMAP is turned on.

Microsoft sign-in

You see	Fix
Need admin approval (AADSTS90094 or AADSTS65001)	Your IT department must approve email-tool. Ask them to grant admin consent to application ID 82731d7a-ac7f-4a5e-88d3-acce522f85ce, or to give you their own app's ID for --client-id.
work needs a new Microsoft sign-in	Run the command in the message. It signs you in again.
The sign-in works but the login check fails	IMAP or authenticated SMTP is turned off for your mailbox. Ask your IT department to turn them on.
No browser opens	Open the sign-in address the terminal prints, then paste back the address the browser ends on. Or use --device-code.

Google sign-in

You see	Fix
Google hasn't verified this app	Expected for your own External client. Select Advanced, then Go to email-tool (unsafe).
Access blocked: ... admin	Your organization blocks apps it has not approved. Ask your IT department to allow your client, or to create an Internal one.
This site can't be reached after you allow access	Run the command again with --paste-address, then paste back the address the browser ends on.
No browser can be opened from here	Open the address the terminal prints in a browser on the same computer, or use --paste-address.
no answer from the browser within 5 minutes	Run the command again and finish the sign-in within 5 minutes.
Google granted less than was asked	Run the command again and leave every permission selected.
signed in as ..., not ...	Gmail logs in as the Google account itself. Use --address with the account you signed in with.
work needs a new Google sign-in	Run the command in the message. A client in Testing ends sign-ins after 7 days: publish it.

Policy and audit log

You see	Fix
A message that starts with policy:	Your organization's policy refused the action. The message names the rule. See For administrators.
Refused, nothing was done: ...	The audit log could not be written, so nothing ran. Check that the log's folder exists and has space (email-tool-mcp audit path).
the log does not match its keyring anchor	The log was changed or replaced. Run email-tool-mcp audit verify and report the result to your security team.
nothing was done: ... looks sensitive or ... is a folder whose files run at login	An attachment looks like a key, credential or CUI file, or the save could make a file run, and your app cannot ask you. Tell the assistant whether to go ahead.
the attachments add up to ...	Mail servers refuse more than 25 MB per message. Send fewer or smaller files, or share a link.
... contains invalid text (a broken Unicode character)	The assistant sent text that is not valid. Ask it to try again.

Still stuck

Ask your assistant to report the problem: it builds a report with nothing private in it, which you read before it is sent. See Report a problem. Or open an issue at github.com/skhan61/email-tool/issues with the message you see and the output of email-tool-mcp list. Remove anything private first. Report security problems privately, as described in the security policy.