hcengineering/platform · error · Error

Missing env variables for SMTP configuration: ${missingKeys.

Error message

Missing env variables for SMTP configuration: ${missingKeys.join(', ')}

What it means

buildSmtpConfig validates the minimum SMTP settings. If SMTP_HOST is missing or SMTP_PORT is unset/unparseable while SMTP mode is active, it throws this error naming the missing keys (SMTP_HOST, SMTP_PORT).

Source

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

  return {
    AccessKey: accessKey as string,
    SecretKey: secretKey as string,
    Region: region as string
  }
}

const buildSmtpConfig = (): SmtpConfig => {
  const host = process.env[envMap.SmtpHost]
  const port = parseNumber(process.env[envMap.SmtpPort])
  const username = process.env[envMap.SmtpUsername]
  const password = process.env[envMap.SmtpPassword]
  const tlsMode = normalizeTlsMode(process.env[envMap.SmtpTlsMode])
  const debugLog = process.env[envMap.SmtpDebugLog]?.toLowerCase() === 'true'
  const allowSelfSigned = process.env[envMap.SmtpAllowSelfSigned]?.toLowerCase() === 'true'

  if (isEmpty(host) || port === undefined) {
    const missingKeys = [isEmpty(host) && 'SMTP_HOST', port === undefined && 'SMTP_PORT'].filter(Boolean)
    throw Error(`Missing env variables for SMTP configuration: ${missingKeys.join(', ')}`)
  }

  return {
    Host: host as string,
    Port: port,
    Username: username,
    Password: password,
    TlsMode: tlsMode ?? TlsOptions.UPGRADE,
    DebugLog: debugLog,
    AllowSelfSigned: allowSelfSigned
  }
}

const config: Config = (() => {
  const port = parseNumber(process.env[envMap.Port])
  if (port === undefined) {
    throw Error('Missing env variable: Port')
  }

View on GitHub (pinned to 63e28dc964)

Solutions

Set both SMTP_HOST and SMTP_PORT (numeric, e.g. 587) in the environment.
Read the error text — it lists exactly which keys are missing.
Verify SMTP_PORT is a plain integer; quoted or whitespace values can fail parsing.
If you intended SES delivery, remove SMTP_HOST so the SMTP path isn't selected.

Example fix

// before
SMTP_HOST=smtp.example.com
// after
SMTP_HOST=smtp.example.com
SMTP_PORT=587

Defensive patterns

Strategy: validation

Validate before calling

if (process.env.SMTP_HOST) { // SMTP path active
  const missing = [];
  if (!process.env.SMTP_HOST) missing.push('SMTP_HOST');
  if (!process.env.SMTP_PORT || Number.isNaN(Number(process.env.SMTP_PORT))) missing.push('SMTP_PORT');
  if (missing.length) throw new Error(`Missing SMTP env vars: ${missing.join(', ')}`);
}

Try / catch

try {
  await import('./config');
} catch (err) {
  if (err instanceof Error && err.message.startsWith('Missing env variables for SMTP')) {
    console.error(`SMTP setup incomplete: ${err.message}`);
    process.exit(1);
  }
  throw err;
}

Prevention

Always pair SMTP_HOST with a numeric SMTP_PORT (587 for STARTTLS, 465 for implicit TLS).
Verify the port parses as an integer — no quotes, units, or whitespace.
Keep SMTP variables together in a single env file/secret so none are dropped.
Remove SMTP_HOST entirely if you intend to use SES.

When it happens

Trigger: Setting SMTP_HOST without SMTP_PORT, or SMTP_PORT set to a non-numeric value that parseNumber rejects, while SMTP configuration is enabled in pod-mail.

Common situations: Choosing SMTP delivery but only supplying host credentials and forgetting the port (usually 587 or 465); port given as an empty string; config split across env files where one file is not loaded.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

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