hcengineering/platform · critical · Error

WORKSPACE_URL env var is not set

Error message

WORKSPACE_URL env var is not set

What it means

The mail worker config module (services/mail/pod-mail-worker/src/config.ts) resolves workspaceUrl via an inline IIFE that returns process.env.WORKSPACE_URL only when defined, and otherwise throws this error. Unlike most settings in that file which have defaults, WORKSPACE_URL is mandatory because the worker must know the workspace (Huly) service address to function.

Source

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

  queueConfig: string
  queueRegion: string
  communicationTopic: string
  serviceId: string
  mailUrl: string
  mailAuth: string
  footerMessage: string
  outgoingSyncStartDate: Date // ISO date string - messages from mail channel before this date will not attempt to be sent to Gmail
}

const config: Config = {
  port: parseInt(process.env.PORT ?? '4050'),
  secret: process.env.SECRET ?? 'secret',
  accountsUrl: process.env.ACCOUNTS_URL ?? 'http://localhost:3000',
  workspaceUrl: (() => {
    if (process.env.WORKSPACE_URL !== undefined) {
      return process.env.WORKSPACE_URL
    }
    throw Error('WORKSPACE_URL env var is not set')
  })(),
  ignoredAddresses: process.env.IGNORED_ADDRESSES?.split(',') ?? [],
  hookToken: process.env.HOOK_TOKEN,
  mailSizeLimit: process.env.MAIL_SIZE_LIMIT ?? '50mb',
  storageConfig: process.env.STORAGE_CONFIG,
  kvsUrl: (() => {
    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 ?? '',

View on GitHub (pinned to 63e28dc964)

Solutions

1. Set WORKSPACE_URL to the workspace service URL (e.g. http://workspace:3000 or the public workspace endpoint) in the worker's environment.
2. Verify service discovery/network policy allows the worker to reach that URL.
3. Run the worker locally with a .env containing WORKSPACE_URL to confirm startup.
4. Consider aligning this file's style with the other services' single missingEnv check to get all missing vars reported at once.

Example fix

// before
WORKSPACE_URL unset -> throw at import
// after
# .env
WORKSPACE_URL=http://workspace:3000

const required = ['WORKSPACE_URL', 'KVS_URL', 'QUEUE_CONFIG', 'MAIL_URL'];
const missing = required.filter((k) => process.env[k] === undefined);
if (missing.length) {
  console.error('Missing mail-worker env vars:', missing.join(', '));
  process.exit(1);
}
new URL(process.env.WORKSPACE_URL!); // must be a valid URL

function isDefined<T>(v: T | undefined): v is T {
  return v !== undefined;
}

try {
  const { default: config } = await import('./src/config.js');
} catch (e) {
  const m = /not set$/.test((e as Error).message) ? 'Set the named env var for the mail worker' : (e as Error).message;
  console.error(`Mail worker config error: ${m}`);
  process.exit(1);
}

When it happens

Trigger: process.env.WORKSPACE_URL is undefined when config.ts is imported (module-load time). It only checks `undefined`, so an empty string would NOT throw here — it would be accepted.

Common situations: Mail worker pod deployed without WORKSPACE_URL; internal service DNS/name changed and the var was dropped; local development without the full set of required mail-worker vars.

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

• Missing config for attributes: ${missingEnv.join(', ')}
• Missing config for attributes: ${missingEnv.join(', ')}
• Missing env variables: ${missingEnv.join(', ')}
• Missing env variables: ${missingEnv.join(', ')}
• Missing env variables: ${missingEnv.join(', ')}

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