hcengineering/platform · critical · Error

Missing env variable: QUEUE_CONFIG

Error message

Missing env variable: QUEUE_CONFIG

What it means

In the gmail service config module (services/gmail/pod-gmail/src/config.ts), when the integration version is V2 and params.QueueConfig is an empty string, this dedicated error is thrown. It exists because an empty QUEUE_CONFIG passes the generic undefined check but is still unusable for V2 queue-based message flow, so the config module fails fast with a precise message.

Source

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

    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. Provide a valid, non-empty QUEUE_CONFIG value (typically a JSON string with queue connection settings) in the environment.
2. Verify with `printenv QUEUE_CONFIG | wc -c` (or equivalent) that it is not empty after deployment.
3. If the integration should remain V1, ensure the version flag actually selects V1 so this check is skipped.
4. Regenerate/recreate the queue config (SQS/queue URL and credentials) and inject it via the secret manager.

Example fix

// before
QUEUE_CONFIG=""
// after
# .env
QUEUE_CONFIG={"queueUrl":"https://sqs.us-east-1.amazonaws.com/123/gmail","region":"us-east-1"}

if (isV2) {
  const q = process.env.QUEUE_CONFIG;
  if (q === undefined || q.trim() === '') {
    throw new Error('Missing env variable: QUEUE_CONFIG');
  }
  JSON.parse(q); // must be valid queue config JSON
}

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: QUEUE_CONFIG') {
    console.error('Provide a non-empty QUEUE_CONFIG for V2 integrations');
  }
  process.exit(1);
}

When it happens

Trigger: IntegrationVersion.V2 active AND process.env.QUEUE_CONFIG is set to an empty string (QUEUE_CONFIG="" in the environment or an empty value in the manifest/.env). Undefined QUEUE_CONFIG instead surfaces in error 1233's list.

Common situations: Migrating a V1 Gmail integration to V2 without provisioning the queue config; deployment template renders QUEUE_CONFIG as empty; queue credentials removed from secrets during rotation.

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: COMMUNICATION_TOPIC
• Missing env variables: ${missingEnv.join(', ')}
• QUEUE_CONFIG env var is not set
• Invalid storage config:${st}
• Please provide queue config

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