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.
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.
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.
Daniel Vázquez
Software Engineer with over 10 years of experience on Startups, Government, big tech industry & consulting.
hanson1014
Full-stack developer experienced in fixing and deploying AI-generated apps from Lovable, Bolt.new, Cursor, and Replit. I specialize in debugging Supabase integration issues (auth flows, RLS policies, database connections), fixing broken deployments, resolving routing/blank screen problems, and cleaning up messy React/Vite codebases. I also build production apps with the Claude API and have shipped a Mac desktop dev tool (Nexterm from scratch. Based in Hong Kong, fast turnaround.
Bastien Labelle
Full stack dev w/ 20+ years of experience
Kingsley Omage
Fullstack software engineer passionate about AI Agents, blockchain, LLMs.
Matthew Butler
Systems Development Engineer @ Amazon Web Services
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.
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.
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.
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.