[BUG]: No graceful error handling when WhatsApp connection fails or times out

[simrannsv]

Describe the bug
When the WhatsApp connection fails, drops, or times out,
the terminal displays a raw unformatted error or crashes
silently. There is no user-friendly error message to
inform the user what went wrong or how to recover.

Steps to Reproduce

1. Start chat-buddy in the terminal
2. Interrupt the WhatsApp connection (disconnect network,
   revoke WhatsApp Web session, or let it time out)
3. Observe the terminal output

Expected Behavior
The application should:

• Display a clear, friendly error message explaining
  what went wrong
• Suggest a recovery action (e.g. "Run the command
  again to reconnect" or "Scan QR code to re-authenticate")
• Exit gracefully without crashing or showing raw
  stack traces to the user

Actual Behavior
Raw error output or silent crash with no guidance
for the user on how to recover.

Impact
This affects every user whose WhatsApp session
expires or connection drops — which is a common
real-world scenario.

Suggested Fix
Add a try/catch wrapper around the WhatsApp
connection initialization with:

• A descriptive error message
• A clean exit or auto-reconnect prompt

Additional Context
Good error handling is critical for a terminal-based
tool where users have no GUI feedback. This would
significantly improve the user experience.

I would love to work on this fix under GSSoC '26.
Please assign this issue to me.

[princeyadaviiit]

Hi @snackoverflowasad I reviewed this issue and I’d love to work on improving the WhatsApp connection error handling.

This is an important UX issue because connection drops, expired sessions, and network interruptions are common scenarios for terminal-based tools. Right now, the raw errors/silent crashes make recovery difficult for users.

I can work on:

• Adding proper try/catch handling around WhatsApp connection initialization
• Displaying clean, user-friendly error messages instead of raw stack traces
• Providing actionable recovery guidance (reconnect, re-scan QR, retry command, etc.)
• Ensuring graceful shutdown without abrupt crashes
• Optionally improving reconnect flow/logging for better debugging

This should make the CLI much more reliable and beginner-friendly.

Please assign this issue to me under GSSoC '26. Thanks!

[snackoverflowasad]

Hi @simrannsv

Thank you for your interest in contributing to this issue.

I apologize for the delayed response. After reviewing the issue, I agree that improving error handling around WhatsApp connection failures would significantly enhance the user experience, especially since connection interruptions and session expirations are common scenarios.

I'm assigning this issue to you.

While implementing the fix, please ensure that:

• Users receive clear and actionable error messages instead of raw stack traces.
• Common failure scenarios such as network interruptions, session expiration, authentication failures, and connection timeouts are handled gracefully.
• Appropriate recovery guidance is provided to help users reconnect or re-authenticate.
• The application exits cleanly or offers a reconnection flow without unexpected crashes.
• Existing functionality remains unaffected and all changes are thoroughly tested.

Additionally, please make sure to keep the README and any relevant documentation up to date by documenting the new error-handling behavior, recovery instructions, and any configuration changes introduced as part of this feature.

When submitting your PR, include screenshots or terminal recordings demonstrating the improved user experience for both successful recovery and failure scenarios.

Thank you for contributing to the project. If you have any questions during implementation, feel free to reach out.

Also, if you haven't already, please consider starring the repository to support the project and its contributors. ⭐

Happy contributing!

[Truptiiio-o]

Hi @snackoverflowasad , i would like to actively work on this issue

[simrannsv]

Hi @snackoverflowasad

The issue has been solved with proper error handling. Kindly check the PR here: #66 . Thanks!