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
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.
Jared Hasson
Full time lead founding dev at a cyber security saas startup, with 10 yoe and a bachelor's in CS. Building & debugging software products is what I've spent my time on for forever
Victor Denisov
Developer
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.
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.
Meïr Ankri
Full-stack developer specializing in React / Next.js / Node.js with 6+ years of experience. I've worked across various sectors including automotive (Reezocar/Société Générale), healthcare (Medical Link SaaS), and e-commerce (Glasman). I build web apps end-to-end, from architecture to production, with a focus on scalability, performance, and code quality. I also mentor junior developers and contribute to technical decisions and code reviews.
PawelPloszaj
I'm fronted developer with 10+ years of experience with big projects. I have small backend background too
Jaime Orts-Caroff
I'm a Senior Android developer, open to work in various fields
BurnHavoc
Been around fixing other peoples code for 20 years.
rayush33
JavaScript (React.js, React Native, Node.js) Developer with demonstrated industry experience of 4+ years, actively looking for opportunities to hone my skills as well as help small-scale business owners with solutions to technical problems
Omar Faruk
As a Product Engineer at Klasio, I contributed to end-to-end product development, focusing on scalability, performance, and user experience.
My work spanned building and refining core features, developing dynamic website templates, integrating secure and reliable payment gateways, and optimizing the overall system architecture.
I played a key role in creating a scalable and maintainable platform to support educators and learners globally.
I'm enthusiastic about embracing new challenges and making meaningful contributions.
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.