What causes "Please specify SES or SMTP configuration" in hcengineering/platform?

Configure exactly one backend: set SMTP_HOST/SMTP_PORT (plus credentials) or SES_ACCESS_KEY/SES_SECRET_KEY/SES_REGION.

hcengineering/platform · error · Error

Please specify SES or SMTP configuration

Error message

Please specify SES or SMTP configuration

What it means

pod-mail requires at least one mail backend configuration. If neither SMTP_HOST nor SES_ACCESS_KEY is present (non-empty) in the environment, the config IIFE throws 'Please specify SES or SMTP configuration' at startup.

Source

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

    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')
  }
  const isSmtpConfig = !isEmpty(process.env[envMap.SmtpHost])
  const isSesConfig = !isEmpty(process.env[envMap.SesAccessKey])
  if (isSmtpConfig && isSesConfig) {
    throw Error('Both SMTP and SES configuration are specified, please specify only one')
  }
  if (!isSmtpConfig && !isSesConfig) {
    throw Error('Please specify SES or SMTP configuration')
  }
  const params: Config = {
    port,
    source: process.env[envMap.Source],
    replyTo: process.env[envMap.ReplyTo],
    sesConfig: isSesConfig ? buildSesConfig() : undefined,
    smtpConfig: isSmtpConfig ? buildSmtpConfig() : undefined
  }

  return params
})()

export default config

View on GitHub (pinned to 63e28dc964)

Solutions

Configure exactly one backend: set SMTP_HOST/SMTP_PORT (plus credentials) or SES_ACCESS_KEY/SES_SECRET_KEY/SES_REGION.
Verify the secret/env file containing mail settings is actually mounted and loaded.
Check variable-name typos — the service only looks at the envMap keys (e.g. SMTP_HOST, SES_ACCESS_KEY).

Example fix

// before
PORT=4001
# no mail backend configured
// after
PORT=4001
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USERNAME=user
SMTP_PASSWORD=pass

Defensive patterns

Strategy: validation

Validate before calling

const smtp = !!process.env.SMTP_HOST;
const ses = !!process.env.SES_ACCESS_KEY;
if (!smtp && !ses) {
  throw new Error('No mail backend configured: set SMTP_HOST/SMTP_PORT or SES_ACCESS_KEY/SES_SECRET_KEY/SES_REGION');
}

Try / catch

try {
  await import('./config');
} catch (err) {
  if (err instanceof Error && err.message.includes('Please specify SES or SMTP')) {
    console.error('No mail backend: configure SMTP or SES env vars for pod-mail');
    process.exit(1);
  }
  throw err;
}

Prevention

Include mail backend vars in the service's base deployment template so fresh deploys never start empty.
Mount the env secret containing SMTP/SES settings and verify it in the pod spec.
Check for variable-name typos against envMap in pod-mail/src/config.ts.
Smoke-test config loading in CI with the production env template.

When it happens

Trigger: Starting pod-mail with Port set but with neither SMTP_HOST nor SES_ACCESS_KEY defined — the mail sender has no delivery backend.

Common situations: Fresh deployment with only infrastructure env vars; accidentally clearing mail variables during a secret rotation; running the image without mounting the env file that carries SMTP/SES settings.

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/66f586f1eb20981a. Report an issue: GitHub.