Connection Issues

Error: operation timed out: tcp connect timeout

• IMAP server is unreachable
• Network connectivity issues
• Firewall blocking outbound connections
• Incorrect hostname or port
• Server is down

​

1. Verify Server Details

​

2. Test Connectivity

# Test TCP connection
nc -zv imap.gmail.com 993

# Or using telnet
telnet imap.gmail.com 993

# Or using openssl
openssl s_client -connect imap.gmail.com:993 -crlf

​

3. Increase Timeout

MAIL_IMAP_CONNECT_TIMEOUT_MS=60000  # 60 seconds (default: 30000)

​

4. Check Firewall Settings

• Corporate networks may block IMAP ports
• VPN or proxy settings may interfere
• Check network security policies

​

5. Verify Server Status

• Gmail: https://www.google.com/appsstatus
• Office 365: https://status.office.com/
• Check provider’s status page

Error: operation timed out: TLS handshake timeout

• TLS negotiation taking too long
• Incompatible TLS versions
• Network latency
• Server overload

​

1. Increase Greeting Timeout

MAIL_IMAP_GREETING_TIMEOUT_MS=30000  # 30 seconds (default: 15000)

​

2. Check Network Quality

• High latency or packet loss can cause TLS timeouts
• Test with ping: ping imap.gmail.com
• Check for network congestion

​

3. Verify TLS Support

# Test TLS connection
openssl s_client -connect imap.gmail.com:993 -tls1_2

Error: operation timed out: IMAP greeting timeout

• Server not sending greeting banner
• Server overloaded
• Network issues after TLS handshake

​

Increase Greeting Timeout

MAIL_IMAP_GREETING_TIMEOUT_MS=30000  # 30 seconds (default: 15000)

​

Test IMAP Greeting

openssl s_client -connect imap.gmail.com:993 -crlf -quiet
# Should see: * OK Gimap ready for requests from...

Error: operation timed out: IMAP login timeout

• Authentication taking too long
• Server processing delay
• Large account with slow mailbox indexing

​

Increase Greeting Timeout

MAIL_IMAP_GREETING_TIMEOUT_MS=30000  # 30 seconds (default: 15000)

​

Notes

• First login after password change may be slower
• Large mailboxes may take longer to authenticate
• Some servers perform indexing during login

Error: operation timed out: UID FETCH timed out

• Large message taking too long to download
• Slow server response
• Network bandwidth limitations

​

Increase Socket Timeout

MAIL_IMAP_SOCKET_TIMEOUT_MS=600000  # 10 minutes (default: 300000)

​

For Large Messages

• Use imap_get_message_raw with appropriate max_bytes limit
• Large attachments may require longer timeouts
• Consider connection quality and bandwidth

Error: operation timed out: UID SEARCH timed out

• Very large mailbox
• Complex search query
• Server performing full-text search
• Slow server

​

1. Increase Socket Timeout

MAIL_IMAP_SOCKET_TIMEOUT_MS=600000  # 10 minutes (default: 300000)

​

2. Narrow Search Query

{
  "account_id": "default",
  "mailbox": "INBOX",
  "last_days": 30,          // Limit to recent messages
  "from": "example.com",    // Filter by sender
  "unread_only": true        // Only unread messages
}

​

3. Search Smaller Mailboxes

Error: operation timed out: NOOP timed out

• Server not responding to keepalive command
• Connection may be dead
• Server overloaded

​

Increase Socket Timeout

MAIL_IMAP_SOCKET_TIMEOUT_MS=600000  # 10 minutes (default: 300000)

​

Check Connection

• This usually indicates a server issue
• Try reconnecting
• Check server status

Error: internal error: tcp connect failed: Connection refused

• Server is not listening on the specified port
• Wrong port number
• Server is down
• Firewall blocking connection

​

1. Verify Port Number

• 993 - IMAP over TLS (default)
• 143 - Plain IMAP (not supported by this server)

​

2. Check Server Status

• Verify the mail server is running
• Check provider status pages
• Test with another IMAP client

​

3. Test Connection

nc -zv imap.gmail.com 993
# Should show: Connection to imap.gmail.com port 993 [tcp/imaps] succeeded!

Error: internal error: TLS handshake failed: certificate verification failed

• Invalid server certificate
• Expired certificate
• Self-signed certificate (not trusted)
• Certificate name mismatch
• System root certificates out of date

​

1. Verify Server Certificate

openssl s_client -connect imap.gmail.com:993 -showcerts
# Check certificate validity and issuer

​

2. Update System Certificates

• Update your system’s root certificates
• On Linux: sudo update-ca-certificates
• On macOS: Certificates update with system updates

​

3. Check Certificate Validity

• Expired certificates: Contact mail provider
• Self-signed certificates: Not supported (use a valid certificate)
• Name mismatch: Ensure hostname matches certificate

​

Note

Error: internal error: IMAP server closed connection before greeting

• Server rejected connection immediately
• Too many concurrent connections
• IP address blocked or rate-limited
• Server maintenance

​

1. Check Connection Limits

• Gmail: Max 15 concurrent connections per account
• Most servers: 3-10 concurrent connections
• Wait a few minutes and retry

​

2. Verify IP Not Blocked

• Check if your IP is rate-limited
• Try from a different network
• Contact email provider if blocked

​

3. Check Server Status

• Server may be in maintenance mode
• Check provider status page