twentyhq/twenty · error · PdlConfigError

CONFIGURATION

CONFIGURATION

Error message

PDL_API_KEY is not set. The workspace admin must configure the People Data Labs API key in Settings -> Apps.

What it means

The People Data Labs enrichment logic function reads `process.env.PDL_API_KEY` (trimmed) and throws a `PdlConfigError` (code `CONFIGURATION`) when it is empty. This is a workspace-admin setup step: the PDL API key must be configured in Settings → Apps before any enrichment runs. The typed error code lets the app surface a dedicated 'configure the integration' message to the user rather than a generic failure.

Source

Thrown at packages/twenty-apps/public/people-data-labs/src/logic-functions/utils/get-pdl-api-key.ts:9

import { isNonEmptyString } from '@sniptt/guards';

import { PdlConfigError } from 'src/logic-functions/errors/pdl-config-error';

export const getPdlApiKey = (): string => {
  const apiKey = process.env.PDL_API_KEY?.trim();

  if (!isNonEmptyString(apiKey)) {
    throw new PdlConfigError(
      'PDL_API_KEY is not set. The workspace admin must configure the People Data Labs API key in Settings -> Apps.',
    );
  }

  return apiKey;
};

View on GitHub (pinned to 1f5dd2bbd2)

Solutions

1. As a workspace admin, open Settings → Apps → People Data Labs and enter a valid PDL API key.
2. Confirm the variable is stored under the exact name `PDL_API_KEY` and is non-empty after trimming.
3. If the error persists after entry, verify the logic-function runtime receives the variable (scope/propagation issue) and re-save the app config.
4. Generate a fresh key from the People Data Labs dashboard if the existing one is invalid/expired.

Example fix

// before
const apiKey = process.env.PDL_API_KEY?.trim();
if (!isNonEmptyString(apiKey)) {
  throw new PdlConfigError('PDL_API_KEY is not set. ...');
}

// after — no code fix resolves this; it is an admin task. Optionally pre-flight in the UI:
// (UI) disable the Enrich button until the key is set, so the user never reaches this throw.
// In code, keep the guard but add a health check the UI can call:
export const isPdlConfigured = (): boolean => isNonEmptyString(process.env.PDL_API_KEY?.trim());

export const isPdlConfigured = (): boolean =>
  isNonEmptyString(process.env.PDL_API_KEY?.trim());

// Gate the UI/enrichment button on this so users never reach getPdlApiKey() unconfigured.
if (!isPdlConfigured()) {
  throw new Error('Configure PDL_API_KEY in Settings → Apps before enriching.');
}

const isPdlApiKey = (v: unknown): v is string =>
  typeof v === 'string' && v.trim().length > 0;

try {
  const apiKey = getPdlApiKey();
  // ... enrich
} catch (error) {
  if (error instanceof PdlConfigError) {
    // Surface a 'configure the integration' message to the user.
    return { status: 'configuration-required', message: error.message };
  }
  throw error;
}

When it happens

Trigger: Any PDL enrichment action triggered before the admin has set `PDL_API_KEY`, or after it was cleared/rotated to an empty value. The check runs at the start of every enrichment entrypoint that calls `getPdlApiKey()`.

Common situations: Newly installed PDL app with no API key entered; an admin cleared the key; the key was set on the wrong variable name or scope so `process.env.PDL_API_KEY` is empty at runtime.

Related errors

• OPERATION_FAILED
• OPERATION_FAILED
• Missing ${name} env var
• Missing ${name} env var
• RECALL_WEBHOOK_SECRET server variable is not set. A server a

AI-assisted analysis of twentyhq/twenty@1f5dd2bbd2 (2026-08-12). Data as JSON: /api/errors/3fbe745df0f4077c. Report an issue: GitHub.