Windsurf
email
Nodemailer TLS Handshake Failed in Windsurf App
Your Windsurf-generated app fails to send emails through Nodemailer with TLS handshake errors. Email functionality that worked in development breaks when deployed, or stops working suddenly after the email provider updates their security settings.
TLS (Transport Layer Security) handshake failures mean your app cannot establish a secure connection to the SMTP server. This blocks all email sending — password resets, notifications, verification emails, and any other transactional emails your app depends on.
The error may be intermittent, working sometimes and failing others, or it may fail consistently after a deployment or SMTP provider change. Common scenarios include moving from development to production, switching email providers, or the provider deprecating old TLS versions.
Error Messages You Might See
Error: self-signed certificate
Error: unable to verify the first certificate
Error: ESOCKET - TLS handshake failed
Error: Connection timeout on port 465
Error: SSL routines:ssl3_get_record:wrong version number
Common Causes
- Wrong port and security combination — Cascade configured port 465 with STARTTLS (should use TLS) or port 587 with direct TLS (should use STARTTLS)
- Self-signed or expired certificate — The SMTP server's SSL certificate is self-signed, expired, or not trusted by Node.js
- TLS version mismatch — The SMTP server requires TLS 1.2+ but the Node.js configuration allows old versions, or vice versa
- rejectUnauthorized set incorrectly — Cascade set rejectUnauthorized: false during development to bypass cert errors, but this is insecure for production
- Firewall blocking SMTP ports — The hosting platform (Vercel, Railway, etc.) blocks outbound SMTP connections on ports 25, 465, or 587
How to Fix It
- Match port to security protocol — Use port 587 with secure: false (STARTTLS upgrades automatically), or port 465 with secure: true (implicit TLS). Never use port 25 for authenticated email
- Verify SMTP credentials — Double-check host, port, username, and password. Many providers require app-specific passwords when 2FA is enabled
- Set proper TLS options — Add tls: { minVersion: 'TLSv1.2', rejectUnauthorized: true } to your Nodemailer transport configuration
- Test SMTP connection independently — Use the nodemailer verify() method to test the connection before sending: transporter.verify().then(console.log).catch(console.error)
- Use an email API instead — If your host blocks SMTP ports, switch from Nodemailer SMTP to an HTTP-based email API (SendGrid, Resend, Postmark) that uses port 443
- Check your hosting platform — Vercel, Netlify, and some serverless platforms block SMTP. Check their docs for email sending limitations
Real developers can help you.
BurnHavoc
Been around fixing other peoples code for 20 years.
Nam Tran
10 years as fullstack developer
Jen Jacobsen
I’m a Full-Stack Developer with over 10 years of experience building modern web and mobile applications. I enjoy working across the full product lifecycle — turning ideas into real, well-built products that are intuitive for users and scalable for businesses.
I particularly enjoy building mobile apps, modern web platforms, and solving complex technical problems in a way that keeps systems clean, reliable, and easy to maintain.
Taufan
I’m a product-focused engineer and tech leader who builds scalable systems and turns ideas into production-ready platforms.
Over the past years, I’ve worked across startups and fast-moving teams, leading backend architecture, improving system reliability, and shipping products used by thousands of users. My strength is not just writing code — but connecting product vision, technical execution, and business impact.
Simon A.
I'm a backend developer building APIs, emulators, and interactive game systems. Professionally, I've developed Java/Spring reporting solutions, managed relational and NoSQL databases, and implemented CI/CD workflows.
Yovel Cohen
I got a lot of experience in building Long-horizon AI Agents in production, Backend apps that scale to millions of users and frontend knowledge as well.
Milan Surelia
Milan Surelia is a Mobile App Developer with 5+ years of experience crafting scalable, cross-platform apps at 7Span and Meticha. At 7Span, he engineers feature-rich Flutter apps with smooth performance and modern UI. As the Co-Founder of Meticha, he builds open-source tools and developer-focused products that solve real-world problems.
Expertise:
💡 Developing cross-platform apps using Flutter, Dart, and Jetpack Compose for Android, iOS, and Web.
🖋️ Sharing insights through technical writing, blogging, and open-source contributions.
🤝 Collaborating closely with designers, PMs, and developers to build seamless mobile experiences.
Notable Achievements:
🎯 Revamped the Vepaar app into Vepaar Store & CRM with a 2x performance boost and smoother UX.
🚀 Launched Compose101 — a Jetpack Compose starter kit to speed up Android development.
🌟 Open source contributions on Github & StackOverflow for Flutter & Dart
🎖️ Worked on improving app performance and user experience with smart solutions.
Milan is always happy to connect, work on new ideas, and explore the latest in technology.
Antriksh Narang
5 years+ Experienced Dev (Specially in Web Development), can help in python, javascript, react, next.js and full stack web dev technologies.
Prakash Prajapati
I’m a Senior Python Developer specializing in building secure, scalable, and highly available systems. I work primarily with Python, Django, FastAPI, Docker, PostgreSQL, and modern AI tooling such as PydanticAI, focusing on clean architecture, strong design principles, and reliable DevOps practices. I enjoy solving complex engineering problems and designing systems that are maintainable, resilient, and built to scale.
David Olverson
Solo dev shipping production apps with AI-assisted development. I specialize in rescuing broken Lovable/Bolt/Cursor builds and taking them to production. 10+ apps shipped including SaaS CRMs, gaming platforms, real estate tools, and Discord bots. Stack: Next.js 16, TypeScript, Tailwind CSS, FastAPI, PostgreSQL, Prisma. I use Claude Code with 50+ custom skills for rapid delivery. Average turnaround: 2-4 weeks from broken prototype to production.
You don't need to be technical. Just describe what's wrong and a verified developer will handle the rest.
Get HelpFrequently Asked Questions
Should I use port 465 or 587 for sending email?
Use port 587 with STARTTLS for most modern SMTP providers. Port 587 starts unencrypted and upgrades to TLS. Port 465 uses implicit TLS and is the legacy standard. Set secure: false for port 587 (Nodemailer handles STARTTLS automatically) and secure: true for port 465.
Is it safe to set rejectUnauthorized: false?
No. Setting rejectUnauthorized: false disables certificate validation, making your connection vulnerable to man-in-the-middle attacks. Only use it for local development. In production, fix the certificate issue instead.