Troubleshooting

Common issues and solutions for outlookctl.

⚙ Quick Diagnostics

Always start with the doctor command to check all prerequisites:

bash
uv run python -m outlookctl.cli doctor

This checks all prerequisites and provides specific remediation advice.

Outlook COM Unavailable

"Outlook COM automation unavailable" OUTLOOK_UNAVAILABLE

Symptoms

  • Error message: "Could not connect to Outlook"
  • Error code: OUTLOOK_UNAVAILABLE

Solutions

1
Classic Outlook not running

Start Outlook manually and wait for it to fully load before retrying.

2
New Outlook is active

New Outlook (the modern app) does NOT support COM automation. Switch to Classic Outlook: Settings > General > Use new Outlook > Off

3
Outlook not installed

Install Microsoft Office with Outlook. Classic Outlook is part of Microsoft 365 / Office suite.

4
COM registration issue

Try repairing Office installation: Settings > Apps > Microsoft 365 > Modify > Repair

pywin32 Not Installed

"pywin32 is not installed" DEPENDENCY

Solution

bash
# Using uv (recommended) uv add pywin32 uv sync # Or with pip pip install pywin32

Folder Not Found

"Folder not found" FOLDER_NOT_FOUND

Solutions

1
Check folder name spelling

Use the standard folder names (case-insensitive):

bash
uv run python -m outlookctl.cli list --folder inbox uv run python -m outlookctl.cli list --folder sent uv run python -m outlookctl.cli list --folder drafts
2
For custom folders, use by-name or by-path
bash
# Search by name uv run python -m outlookctl.cli list --folder "by-name:Projects" # Search by path uv run python -m outlookctl.cli list --folder "by-path:Inbox/Projects/2025"

Message Not Found

"Message not found" MESSAGE_NOT_FOUND

Causes

  • Message was deleted or moved
  • Entry ID has expired (IDs can become stale)
  • Wrong store ID provided

Solutions

1
Re-run list or search to get fresh IDs

Message IDs can expire. Run list or search again to get current IDs.

2
Ensure both IDs are from the same message

Both --id and --store must be from the same message result.

Send Confirmation Required

"Send confirmation required" CONFIRMATION_REQUIRED

This is intentional

  • You must provide explicit confirmation to send

Solution

bash
# For sending a draft uv run python -m outlookctl.cli send \ --draft-id "..." \ --draft-store "..." \ --confirm-send YES # For sending new message directly (not recommended) uv run python -m outlookctl.cli send \ --to "recipient@example.com" \ --subject "Subject" \ --body-text "Body" \ --unsafe-send-new \ --confirm-send YES

Attachment Errors

"Attachment not found" ATTACHMENT_ERROR

When creating draft

✓

Verify the file path exists, use absolute paths for reliability, and check file permissions.

When saving attachments

✓

Ensure the message actually has attachments (has_attachments: true) and verify the destination directory is writable.

Unicode/Encoding Errors

"UnicodeDecodeError" ENCODING

Symptoms

  • Garbled characters in output
  • UnicodeDecodeError exceptions

Solutions

1
Ensure terminal supports UTF-8

Try PowerShell Core instead of cmd.exe

2
Set environment variable
powershell
$env:PYTHONIOENCODING = "utf-8"

Outlook Security Prompts

"A program is trying to access email..." SECURITY

Solutions

1
Click Allow

One-time approval for the current operation

2
Trust Center settings (Outlook)

File > Options > Trust Center > Trust Center Settings > Programmatic Access - Set to "Never warn me"

3
Group Policy (enterprise)

Contact IT for policy configuration

Slow Performance

Commands running slowly PERFORMANCE

For large mailboxes

✓

Use --count to limit results, add date filters (--since, --until), and search specific folders instead of all.

COM initialization

✓

First command may be slow as COM initializes. Subsequent commands are faster.

Environment-Specific Issues

🖥 Windows Server / RDP

Ensure Outlook is running in the same session. COM may not work across sessions. Run both Outlook and outlookctl in the same RDP session.

💻 Virtual Machines

COM works in VMs with Outlook installed. Ensure adequate memory for Outlook.

🐧 WSL

COM automation requires Windows-native Python. Call outlookctl via PowerShell: powershell.exe -c "uv run python -m outlookctl.cli ..."

Getting Help

If issues persist, gather this information:

1

Run uv run python -m outlookctl.cli doctor and note all failures

2

Check Outlook is Classic (not New Outlook)

3

Try restarting Outlook

4

Verify pywin32: python -c "import win32com.client; print('OK')"

Version Information

Include version info when reporting issues:

bash
uv run python -m outlookctl.cli --version