hcengineering/platform · error · Error

Missing env variables: ${missingEnv.join(', ')}

Error message

Missing env variables: ${missingEnv.join(', ')}

What it means

The collaborator service config module builds its Config object at import time (IIFE) and throws if any of the required entries — Secret, ServiceID, Port, AccountsUrl — resolve to undefined. Because config is created on module load, the error appears immediately when the process starts, not on first use.

Source

Thrown at server/collaborator/src/config.ts:58

}

const required: Array<keyof Config> = ['Secret', 'ServiceID', 'Port', 'AccountsUrl']

const config: Config = (() => {
  const params: Partial<Config> = {
    Secret: process.env[envMap.Secret],
    ServiceID: process.env[envMap.ServiceID] ?? 'collaborator-service',
    Interval: parseInt(process.env[envMap.Interval] ?? '30000'),
    Port: parseInt(process.env[envMap.Port] ?? '3078'),
    AccountsUrl: process.env[envMap.AccountsUrl],
    StorageRetryCount: parseInt(process.env[envMap.StorageRetryCount] ?? '5'),
    StorageRetryInterval: parseInt(process.env[envMap.StorageRetryInterval] ?? '50')
  }

  const missingEnv = required.filter((key) => params[key] === undefined).map((key) => envMap[key])

  if (missingEnv.length > 0) {
    throw Error(`Missing env variables: ${missingEnv.join(', ')}`)
  }

  return params as Config
})()

export default config

View on GitHub (pinned to 63e28dc964)

Solutions

  1. Set the env vars listed in the message: typically SECRET and ACCOUNTS_URL (SERVICE_ID/COLLABORATOR_PORT have defaults).
  2. Ensure the k8s Secret providing SECRET is mounted and the env key matches exactly.
  3. Add a .env file or docker --env-file when running locally.
  4. If a var should be optional, add a `?? default` fallback and remove it from the `required` array.

Example fix

// before
node bundle.js  # SECRET unset
// after
export SECRET=$(cat /etc/secrets/secret)
export ACCOUNTS_URL=https://accounts.example.com
node bundle.js
Defensive patterns

Strategy: validation

Validate before calling

const required = ['SECRET','SERVICE_ID','PORT','ACCOUNTS_URL']
const missing = required.filter((k) => process.env[k] === undefined)
if (missing.length > 0) throw new Error(`Missing env variables: ${missing.join(', ')}`)

Type guard

function hasEnv(key: string): boolean {
  return process.env[key] !== undefined
}

Try / catch

// config is created at import time; wrap the import
let config
try {
  config = (await import('./config.js')).default
} catch (err) {
  if ((err as Error).message.startsWith('Missing env variables:')) {
    console.error('collaborator config error:', err.message)
    process.exit(1)
  }
  throw err
}

Prevention

When it happens

Trigger: Importing server/collaborator/src/config.ts without env vars SECRET, SERVICE_ID, PORT, or ACCOUNTS_URL set. Port and ServiceID have defaults ('3078' and 'collaborator-service') but are still in `required`, so they trigger too if explicitly set to undefined only; practically SECRET and ACCOUNTS_URL are the usual culprits. The message names the env var(s), e.g. 'SECRET'.

Common situations: Running collaborator locally without a .env; k8s secret not mounted so SECRET is absent; forgetting ACCOUNTS_URL when pointing at a different accounts service.

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