hcengineering/platform · error · Error

Invalid SMTP_TLS_MODE value. Must be one of: secure, upgrade

Error message

Invalid SMTP_TLS_MODE value. Must be one of: secure, upgrade, ignore

What it means

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.

Source

Thrown at services/mail/pod-mail/src/config.ts:95

  SesRegion: 'SES_REGION',
  SmtpHost: 'SMTP_HOST',
  SmtpPort: 'SMTP_PORT',
  SmtpUsername: 'SMTP_USERNAME',
  SmtpPassword: 'SMTP_PASSWORD',
  SmtpTlsMode: 'SMTP_TLS_MODE', // TLS mode, see TlsOptions for possible values
  SmtpDebugLog: 'SMTP_DEBUG_LOG', // Enable debug logging for SMTP
  SmtpAllowSelfSigned: 'SMTP_ALLOW_SELF_SIGNED' // Allow self-signed certificates (not recommended for production use)
}

const parseNumber = (str: string | undefined): number | undefined => (str !== undefined ? Number(str) : undefined)
const isEmpty = (str: string | undefined): boolean => str === undefined || str.trim().length === 0

const normalizeTlsMode = (mode: string | undefined): TlsOptions | undefined => {
  if (mode === undefined || mode === '') return undefined
  const normalized = mode.toLowerCase()
  const value: TlsOptions | undefined = Object.values(TlsOptions).find((opt) => opt.toLowerCase() === normalized)
  if (value === undefined) {
    throw Error('Invalid SMTP_TLS_MODE value. Must be one of: secure, upgrade, ignore')
  }
  return value
}

const buildSesConfig = (): SesConfig => {
  const accessKey = process.env[envMap.SesAccessKey]
  const secretKey = process.env[envMap.SesSecretKey]
  const region = process.env[envMap.SesRegion]

  if (isEmpty(accessKey) || isEmpty(secretKey) || isEmpty(region)) {
    const missingKeys = [
      isEmpty(accessKey) && 'SES_ACCESS_KEY',
      isEmpty(secretKey) && 'SES_SECRET_KEY',
      isEmpty(region) && 'SES_REGION'
    ].filter(Boolean)
    throw Error(`Missing env variables for SES configuration: ${missingKeys.join(', ')}`)
  }

View on GitHub (pinned to 63e28dc964)

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.

Example fix

// before
SMTP_TLS_MODE=starttls
// after
SMTP_TLS_MODE=upgrade

Defensive patterns

Strategy: validation

Validate before calling

const TLS_MODES = ['secure', 'upgrade', 'ignore'];
const raw = process.env.SMTP_TLS_MODE;
if (raw !== undefined && raw !== '' && !TLS_MODES.includes(raw.toLowerCase())) {
  throw new Error(`SMTP_TLS_MODE must be one of ${TLS_MODES.join(', ')}, got: ${raw}`);
}

Type guard

function isValidTlsMode(v: unknown): v is 'secure' | 'upgrade' | 'ignore' {
  return typeof v === 'string' &&
    ['secure', 'upgrade', 'ignore'].includes(v.toLowerCase());
}

Try / catch

try {
  await import('./config');
} catch (err) {
  if (err instanceof Error && err.message.startsWith('Invalid SMTP_TLS_MODE')) {
    console.error(`Bad SMTP_TLS_MODE: ${err.message}`);
    process.exit(1);
  }
  throw err;
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

AI-assisted analysis of hcengineering/platform@63e28dc964 (2026-08-29). Data as JSON: /api/errors/8f25c790993de167. Report an issue: GitHub.