What causes "MAIL_URL env var is not set" in hcengineering/platform?

Set MAIL_URL to the mail service endpoint (e.g. the pod-mail service URL) in the worker's environment before startup.

hcengineering/platform · error · Error

MAIL_URL env var is not set

Error message

MAIL_URL env var is not set

What it means

At startup, pod-mail-worker's config.ts builds a config object and requires MAIL_URL to be present in the environment. Unlike most settings in this file, MAIL_URL has no default value, so if it is undefined an Error('MAIL_URL env var is not set') is thrown during module initialization, crashing the worker before it starts.

Source

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

    if (process.env.KVS_URL !== undefined) {
      return process.env.KVS_URL
    }
    throw Error('KVS_URL env var is not set')
  })(),
  queueConfig: (() => {
    if (process.env.QUEUE_CONFIG !== undefined) {
      return process.env.QUEUE_CONFIG
    }
    throw Error('QUEUE_CONFIG env var is not set')
  })(),
  queueRegion: process.env.QUEUE_REGION ?? '',
  communicationTopic: process.env.COMMUNICATION_TOPIC ?? 'hulygun',
  serviceId: process.env.SERVICE_ID ?? 'huly-mail',
  mailUrl: (() => {
    if (process.env.MAIL_URL !== undefined) {
      return process.env.MAIL_URL
    }
    throw Error('MAIL_URL env var is not set')
  })(),
  mailAuth: process.env.MAIL_AUTH ?? '',
  footerMessage: process.env.FOOTER_MESSAGE ?? '<br><br><p>Sent via <a href="https://huly.io">Huly</a></p>',
  outgoingSyncStartDate: new Date(process.env.OUTGOING_SYNC_START_DATE ?? '2025-08-20T00:00:00.000Z')
}

export default config

View on GitHub (pinned to 63e28dc964)

Solutions

Set MAIL_URL to the mail service endpoint (e.g. the pod-mail service URL) in the worker's environment before startup.
If using docker/k8s, add MAIL_URL to the env section or secret and redeploy.
If running locally, export MAIL_URL=... in your shell or add it to your .env file.
Check for typos in the variable name (must be exactly MAIL_URL).

Example fix

// before (missing)
# docker-compose.yml
mail-worker:
  environment:
    - SERVICE_ID=huly-mail
// after
mail-worker:
  environment:
    - SERVICE_ID=huly-mail
    - MAIL_URL=http://pod-mail:4001

Defensive patterns

Strategy: validation

Validate before calling

// Run before starting the mail worker
const required = ['MAIL_URL'];
const missing = required.filter((k) => process.env[k] === undefined || process.env[k] === '');
if (missing.length > 0) {
  throw new Error(`Missing required env vars: ${missing.join(', ')}`);
}

Try / catch

try {
  await import('./config');
  startWorker();
} catch (err) {
  if (err instanceof Error && err.message.includes('env var')) {
    console.error(`Environment misconfiguration: ${err.message}`);
    process.exit(1);
  }
  throw err;
}

Prevention

Validate the full required env set in CI and at container startup before the app runs.
Use a checked-in .env.example listing MAIL_URL and diff real envs against it.
In docker-compose/k8s, declare MAIL_URL explicitly in env/secret mappings so omissions are visible.
Prefer a schema validator (zod, envalid) over ad-hoc env reads.

When it happens

Trigger: Running the mail-worker service without MAIL_URL set in the environment (e.g. docker-compose / k8s manifest / .env omitting it, or a typo like MAILURL).

Common situations: Deploying the Huly mail worker fresh without copying the full example env file; renaming the variable in one deployment tool but not another; running the service locally outside the dev container that normally provides MAIL_URL.

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