hcengineering/platform · error · Error

Missing env variable: Port

Error message

Missing env variable: Port

What it means

pod-mail's config IIFE requires the server Port env variable via parseNumber; if it is undefined (or not parseable as a number), it throws 'Missing env variable: Port' during module load, preventing the service from starting.

Source

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

    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')
  }
  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

View on GitHub (pinned to 63e28dc964)

Solutions

1. Set the Port env variable (the name comes from envMap.Port in config.ts — check it, commonly 'PORT') to a numeric value like 4001.
2. Confirm the variable is numeric — parseNumber rejects non-numeric strings.
3. Check the envMap in pod-mail/src/config.ts to confirm the exact expected variable name.
4. Ensure your .env / secret is actually loaded (working directory, env_file directives).

Example fix

// before
# .env missing port
MAIL_HOST=...
// after
PORT=4001
MAIL_HOST=...

const port = Number(process.env.PORT);
if (!process.env.PORT || Number.isNaN(port)) {
  throw new Error(`Missing or non-numeric Port env var: ${process.env.PORT}`);
}

try {
  await import('./config');
} catch (err) {
  if (err instanceof Error && err.message === 'Missing env variable: Port') {
    console.error('Set the Port env variable (numeric) before starting pod-mail');
    process.exit(1);
  }
  throw err;
}

When it happens

Trigger: Starting pod-mail without the Port env var set, or with a non-numeric value that parseNumber cannot parse into a defined number.

Common situations: Missing the PORT entry in .env or deployment manifest; wrong envMap key so the expected variable name differs from what is set; local run without docker env defaults.

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

• MAIL_URL env var is not set
• Missing env variables for SES configuration: ${missingKeys.j
• Missing env variables for SMTP configuration: ${missingKeys.
• Please specify SES or SMTP configuration
• Missing env variables: ${missingEnv.join(', ')}

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