hcengineering/platform · critical · Error

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

Error message

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

What it means

The gmail service config module (services/gmail/pod-gmail/src/config.ts) validates params at import time, mapping missing keys to their env var names via envMap, and throws this error listing the unset variables. V2 integrations get additional checks afterwards (QUEUE_CONFIG, COMMUNICATION_TOPIC non-empty). This fail-fast guard prevents starting a Gmail integration with incomplete config.

Source

Thrown at services/gmail/pod-gmail/src/config.ts:92

    WATCH_TOPIC_NAME: process.env[envMap.WATCH_TOPIC_NAME],
    InitLimit: parseNumber(process.env[envMap.InitLimit]) ?? 50,
    FooterMessage: process.env[envMap.FooterMessage] ?? '<br><br><p>Sent via <a href="https://huly.io">Huly</a></p>',
    OutgoingSyncStartDate: new Date(process.env[envMap.OutgoingSyncStartDate] ?? '2025-08-20T00:00:00.000Z'),
    KvsUrl: process.env[envMap.KvsUrl],
    StorageConfig: process.env[envMap.StorageConfig],
    Version: version,
    QueueConfig: process.env[envMap.QueueConfig] ?? '',
    QueueRegion: process.env[envMap.QueueRegion] ?? '',
    CommunicationTopic: process.env[envMap.CommunicationTopic] ?? 'hulygun',
    WorkspaceInactivityInterval: parseNumber(process.env[envMap.WorkspaceInactivityInterval] ?? '3') // In days
  }

  const missingEnv = (Object.keys(params) as Array<keyof Config>)
    .filter((key) => params[key] === undefined)
    .map((key) => envMap[key])

  if (missingEnv.length > 0) {
    throw Error(`Missing env variables: ${missingEnv.join(', ')}`)
  }
  if (version === IntegrationVersion.V2) {
    if (params.QueueConfig === '') {
      throw Error('Missing env variable: QUEUE_CONFIG')
    }
    if (params.CommunicationTopic === '') {
      throw Error('Missing env variable: COMMUNICATION_TOPIC')
    }
  }

  return params as Config
})()

export default config

View on GitHub (pinned to 63e28dc964)

Solutions

1. Set every env variable named in the error message before starting the service.
2. If the error names QUEUE_CONFIG or COMMUNICATION_TOPIC as undefined, set them — for V2 they are additionally checked for empty strings.
3. Review envMap in config.ts to map each name to its Config key and expected format (e.g. JSON queue config).
4. Run a local import of config.ts with your .env to verify all variables resolve.

Example fix

// before
GMAIL_CLIENT_ID unset -> throw at import
// after
# .env
GMAIL_CLIENT_ID=xxxx.apps.googleusercontent.com

const required: string[] = [/* envMap values for gmail config */];
const missing = required.filter((k) => process.env[k] === undefined);
if (missing.length) throw new Error(`Missing env variables: ${missing.join(', ')}`);

function isNonEmpty(v: string | undefined): v is string {
  return v !== undefined && v.trim().length > 0;
}

try {
  const { default: config } = await import('./src/config.js');
} catch (e) {
  console.error(`Gmail config error: ${(e as Error).message}`);
  process.exit(1);
}

When it happens

Trigger: Any required env var backing a params key is undefined at import (the message shows envMap names). Note: params values that are empty strings '' do NOT trigger this error — they fall through to the V2-specific checks (errors 1234/1235).

Common situations: Gmail pod deployed without required Google OAuth/queue env vars; upgrading an integration to V2 where QUEUE_CONFIG becomes mandatory; missing .env in local development.

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 variable: QUEUE_CONFIG
• Missing env variable: COMMUNICATION_TOPIC

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