{"record":{"id":"8f25c790993de167","repo":"hcengineering/platform","slug":"invalid-smtp-tls-mode-value-must-be-one-of-secur","errorCode":null,"errorMessage":"Invalid SMTP_TLS_MODE value. Must be one of: secure, upgrade, ignore","messagePattern":"Invalid SMTP_TLS_MODE value\\. Must be one of: secure, upgrade, ignore","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"services/mail/pod-mail/src/config.ts","lineNumber":95,"sourceCode":"  SesRegion: 'SES_REGION',\n  SmtpHost: 'SMTP_HOST',\n  SmtpPort: 'SMTP_PORT',\n  SmtpUsername: 'SMTP_USERNAME',\n  SmtpPassword: 'SMTP_PASSWORD',\n  SmtpTlsMode: 'SMTP_TLS_MODE', // TLS mode, see TlsOptions for possible values\n  SmtpDebugLog: 'SMTP_DEBUG_LOG', // Enable debug logging for SMTP\n  SmtpAllowSelfSigned: 'SMTP_ALLOW_SELF_SIGNED' // Allow self-signed certificates (not recommended for production use)\n}\n\nconst parseNumber = (str: string | undefined): number | undefined => (str !== undefined ? Number(str) : undefined)\nconst isEmpty = (str: string | undefined): boolean => str === undefined || str.trim().length === 0\n\nconst normalizeTlsMode = (mode: string | undefined): TlsOptions | undefined => {\n  if (mode === undefined || mode === '') return undefined\n  const normalized = mode.toLowerCase()\n  const value: TlsOptions | undefined = Object.values(TlsOptions).find((opt) => opt.toLowerCase() === normalized)\n  if (value === undefined) {\n    throw Error('Invalid SMTP_TLS_MODE value. Must be one of: secure, upgrade, ignore')\n  }\n  return value\n}\n\nconst buildSesConfig = (): SesConfig => {\n  const accessKey = process.env[envMap.SesAccessKey]\n  const secretKey = process.env[envMap.SesSecretKey]\n  const region = process.env[envMap.SesRegion]\n\n  if (isEmpty(accessKey) || isEmpty(secretKey) || isEmpty(region)) {\n    const missingKeys = [\n      isEmpty(accessKey) && 'SES_ACCESS_KEY',\n      isEmpty(secretKey) && 'SES_SECRET_KEY',\n      isEmpty(region) && 'SES_REGION'\n    ].filter(Boolean)\n    throw Error(`Missing env variables for SES configuration: ${missingKeys.join(', ')}`)\n  }\n","sourceCodeStart":77,"sourceCodeEnd":113,"githubUrl":"https://github.com/hcengineering/platform/blob/63e28dc96483967b2fc21c881b3f1023c1de7718/services/mail/pod-mail/src/config.ts#L77-L113","documentation":"pod-mail's normalizeTlsMode parses the SMTP_TLS_MODE env var by case-insensitively matching it against the TlsOptions enum (secure, upgrade, ignore). If the variable is set to any other non-empty string, it throws this error during config construction at startup.","triggerScenarios":"Setting SMTP_TLS_MODE to an unrecognized value such as 'ssl', 'tls', 'starttls', 'STARTTLS-upgrade', or an accidental trailing character like 'upgrade ' — any non-empty value not equal (case-insensitively) to secure/upgrade/ignore.","commonSituations":"Copy-pasting TLS mode values from other mail libraries (nodemailer uses different names like 'starttls'); admins writing 'ssl' assuming SSL terminology; typos in deployment configs.","solutions":["Set SMTP_TLS_MODE to exactly one of: secure, upgrade, or ignore (case-insensitive).","If you don't need TLS customization, unset SMTP_TLS_MODE entirely — empty/undefined returns undefined without error.","Replace legacy names: use 'secure' for implicit TLS (465), 'upgrade' for STARTTLS, 'ignore' for no TLS.","Trim the value in your deployment config to remove accidental whitespace."],"exampleFix":"// before\nSMTP_TLS_MODE=starttls\n// after\nSMTP_TLS_MODE=upgrade","handlingStrategy":"validation","validationCode":"const TLS_MODES = ['secure', 'upgrade', 'ignore'];\nconst raw = process.env.SMTP_TLS_MODE;\nif (raw !== undefined && raw !== '' && !TLS_MODES.includes(raw.toLowerCase())) {\n  throw new Error(`SMTP_TLS_MODE must be one of ${TLS_MODES.join(', ')}, got: ${raw}`);\n}","typeGuard":"function isValidTlsMode(v: unknown): v is 'secure' | 'upgrade' | 'ignore' {\n  return typeof v === 'string' &&\n    ['secure', 'upgrade', 'ignore'].includes(v.toLowerCase());\n}","tryCatchPattern":"try {\n  await import('./config');\n} catch (err) {\n  if (err instanceof Error && err.message.startsWith('Invalid SMTP_TLS_MODE')) {\n    console.error(`Bad SMTP_TLS_MODE: ${err.message}`);\n    process.exit(1);\n  }\n  throw err;\n}","preventionTips":["Only use secure, upgrade, or ignore (any casing) for SMTP_TLS_MODE.","Unset the variable entirely instead of inventing a value when TLS is not customized.","Do not copy TLS mode names from other libraries (e.g. nodemailer's 'starttls').","Trim whitespace from env values in deployment templates."],"tags":["env","configuration","tls","smtp","validation"],"backgroundTag":"invalid-config-value","analyzedSha":"63e28dc96483967b2fc21c881b3f1023c1de7718","analyzedAt":"2026-08-29T15:21:27.377Z","schemaVersion":2},"datasetVersion":"2026-08-29T17:17:51.833Z"}