{"record":{"id":"5d6cb3ddbc75574c","repo":"immich-app/immich","slug":"failed-to-verify-smtp-configuration","errorCode":null,"errorMessage":"Failed to verify SMTP configuration","messagePattern":"Failed to verify SMTP configuration","errorType":"http","errorClass":"BadRequestException","httpStatus":400,"severity":"error","filePath":"server/src/services/notification-admin.service.ts","lineNumber":34,"sourceCode":"      level: dto.level ?? NotificationLevel.Info,\n      title: dto.title,\n      description: dto.description,\n      data: dto.data,\n    });\n\n    return mapNotification(item);\n  }\n\n  async sendTestEmail(id: string, dto: SystemConfigSmtpDto, tempTemplate?: string) {\n    const user = await this.userRepository.get(id, { withDeleted: false });\n    if (!user) {\n      throw new Error('User not found');\n    }\n\n    try {\n      await this.emailRepository.verifySmtp(dto.transport);\n    } catch (error) {\n      throw new BadRequestException('Failed to verify SMTP configuration', { cause: error });\n    }\n\n    const { server } = await this.getConfig({ withCache: false });\n    const { html, text } = await this.emailRepository.renderEmail({\n      template: EmailTemplate.TEST_EMAIL,\n      data: {\n        baseUrl: getExternalDomain(server),\n        displayName: user.name,\n      },\n      customTemplate: tempTemplate!,\n    });\n    const { messageId } = await this.emailRepository.sendEmail({\n      to: user.email,\n      subject: 'Test email from Immich',\n      html,\n      text,\n      from: dto.from,\n      replyTo: dto.replyTo || dto.from,","sourceCodeStart":16,"sourceCodeEnd":52,"githubUrl":"https://github.com/immich-app/immich/blob/e55ac299a4ec7cb372e35dbf2c6c05ee9ce77f6c/server/src/services/notification-admin.service.ts#L16-L52","documentation":"Thrown by NotificationAdminService.sendTestEmail when the SMTP transport supplied in the test-email request fails verifySmtp, meaning Immich could not establish/authenticate an SMTP session with the provided configuration. The original transport error is attached as the exception cause. The test email is aborted before rendering.","triggerScenarios":"Calling the admin test-email endpoint (POST /notifications/admin/test-email) with dto.transport whose host/port/credentials are wrong, the server is unreachable, TLS settings mismatch, or authentication fails during verifySmtp.","commonSituations":"Typo in SMTP host or port; using port 465 with STARTTLS (or 587 with implicit TLS) so the handshake fails; wrong username/password or OAuth settings; corporate firewall blocking outbound SMTP; mail provider requiring an app password.","solutions":["Read the `cause` of the error for the underlying SMTP failure (auth failed, connection refused, TLS error) and fix that specific issue","Confirm host, port, and security mode match your provider (e.g. 465 = TLS, 587 = STARTTLS)","Test credentials by logging into the mail provider; use an app password if 2FA is enabled","Verify the Immich server container can reach the SMTP host (network/firewall/DNS)"],"exampleFix":"// before\n{ \"transport\": { \"host\": \"smtp.gmail.com\", \"port\": 587, \"secure\": true } } // secure:true on 587 fails handshake\n// after\n{ \"transport\": { \"host\": \"smtp.gmail.com\", \"port\": 587, \"secure\": false } } // STARTTLS on submission port","handlingStrategy":"try-catch","validationCode":"const net = require('net');\nconst reachable = await new Promise(res => {\n  const s = net.connect(transport.port, transport.host);\n  s.once('connect', () => { s.end(); res(true); });\n  s.once('error', () => res(false));\n  s.setTimeout(5000, () => { s.destroy(); res(false); });\n});\nif (!reachable) throw new Error(`Cannot reach SMTP host ${transport.host}:${transport.port}`);","typeGuard":"function hasValidSmtpTransport(t) {\n  return !!t && typeof t.host === 'string' && t.host.length > 0 && Number.isInteger(t.port) && t.port > 0;\n}","tryCatchPattern":"try {\n  await api.notificationsApi.sendTestEmail(transport);\n} catch (e) {\n  if (String(e.message).includes('Failed to verify SMTP configuration')) {\n    console.error('SMTP verify failed:', e.cause ?? e.response?.data); // inspect underlying cause\n  } else throw e;\n}","preventionTips":["Match security mode to port (465 = implicit TLS, 587 = STARTTLS)","Verify credentials with the mail provider and use app passwords where 2FA is on","Test DNS/firewall reachability of the SMTP host from the server container","Read the error's cause field to pinpoint auth vs connection vs TLS failures"],"tags":["smtp","email","network","bad-request"],"backgroundTag":"invalid-config-value","analyzedSha":"e55ac299a4ec7cb372e35dbf2c6c05ee9ce77f6c","analyzedAt":"2026-09-15T07:20:19.675Z","contentChangedAt":"2026-09-15T07:20:19.675Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}