hcengineering/platform · critical · Error

Missing env variable: COMMUNICATION_TOPIC

Error message

Missing env variable: COMMUNICATION_TOPIC

What it means

In the gmail service config module (services/gmail/pod-gmail/src/config.ts), when the integration is V2 and params.CommunicationTopic is an empty string, this error is thrown. V2 integrations require a communication topic for inter-service messaging; an empty value passes the generic undefined check, so this explicit check catches it with a targeted message.

Source

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

    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 COMMUNICATION_TOPIC to the correct topic name/ARN in the service environment.
2. Confirm the topic exists in the messaging infrastructure and the pod's credentials can access it.
3. If V2 behavior is unintended, correct the version configuration so the V2 checks are skipped.
4. Add a startup smoke test importing config.ts to catch empty-string envs before deploy.

Example fix

// before
COMMUNICATION_TOPIC=""
// after
# .env
COMMUNICATION_TOPIC=arn:aws:sns:us-east-1:123:communication

if (isV2) {
  const t = process.env.COMMUNICATION_TOPIC;
  if (t === undefined || t.trim() === '') {
    throw new Error('Missing env variable: COMMUNICATION_TOPIC');
  }
}

function isNonEmptyString(v: unknown): v is string {
  return typeof v === 'string' && v.trim().length > 0;
}

try {
  const { default: config } = await import('./src/config.js');
} catch (e) {
  if ((e as Error).message === 'Missing env variable: COMMUNICATION_TOPIC') {
    console.error('Provide a non-empty COMMUNICATION_TOPIC for V2 integrations');
  }
  process.exit(1);
}

When it happens

Trigger: IntegrationVersion.V2 active AND process.env.COMMUNICATION_TOPIC is set but empty (COMMUNICATION_TOPIC=""). A truly undefined value instead appears in the missingEnv list of error 1233.

Common situations: V2 migration where the topic ARN/name was never provisioned; empty placeholder in deployment template; topic removed during infra cleanup while the service still references it.

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 env variable: QUEUE_CONFIG
• Missing env variables: ${missingEnv.join(', ')}
• Invalid storage config:${st}
• Missing config for attributes: ${missingEnv.join(', ')}
• Missing config for attributes: ${missingEnv.join(', ')}

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