twentyhq/twenty · critical · Error

${caller}() requires the app runtime env vars ${DEFAULT_API_

Error message

${caller}() requires the app runtime env vars ${DEFAULT_API_URL_NAME} and ${DEFAULT_APP_ACCESS_TOKEN_NAME}.

What it means

Thrown by postGraphqlRequest (the core SDK GraphQL transport) when either TWENTY_API_URL or TWENTY_APP_ACCESS_TOKEN environment variables is missing or empty. These two env vars are the minimum runtime configuration for any SDK logic function that calls the Twenty metadata API. Without them, the function cannot construct a valid request URL or Authorization header.

Source

Thrown at packages/twenty-sdk/src/sdk/logic-function/utils/post-graphql-request.util.ts:19

import {
  DEFAULT_API_URL_NAME,
  DEFAULT_APP_ACCESS_TOKEN_NAME,
} from 'twenty-shared/application';

export const postGraphqlRequest = async <TVariables, TData>({
  query,
  variables,
  caller,
}: {
  query: string;
  variables: TVariables;
  caller: string;
}): Promise<TData> => {
  const apiUrl = process.env[DEFAULT_API_URL_NAME];
  const accessToken = process.env[DEFAULT_APP_ACCESS_TOKEN_NAME];

  if (!apiUrl || !accessToken) {
    throw new Error(
      `${caller}() requires the app runtime env vars ` +
        `${DEFAULT_API_URL_NAME} and ${DEFAULT_APP_ACCESS_TOKEN_NAME}.`,
    );
  }

  const response = await fetch(`${apiUrl}/metadata`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${accessToken}`,
    },
    body: JSON.stringify({ query, variables }),
  });

  if (!response.ok) {
    throw new Error(
      `${caller}() failed: HTTP ${response.status} ${response.statusText}`,
    );

View on GitHub (pinned to 1f5dd2bbd2)

Solutions

Set TWENTY_API_URL to your Twenty instance URL (e.g. https://api.twenty.com).
Set TWENTY_APP_ACCESS_TOKEN to a valid app access token obtained via the SDK CLI auth flow.
Ensure your environment loader (dotenv, etc.) runs before any SDK logic function is called.
Verify the variable names exactly match TWENTY_API_URL and TWENTY_APP_ACCESS_TOKEN.

Example fix

// before — env vars not set
import { getConnection } from 'twenty-sdk';
const conn = await getConnection('conn-123');

// after — ensure env vars are loaded
import 'dotenv/config'; // or set them in your deployment environment
// process.env.TWENTY_API_URL = 'https://api.twenty.com'
// process.env.TWENTY_APP_ACCESS_TOKEN = '...'
const conn = await getConnection('conn-123');

Defensive patterns

Strategy: validation

Validate before calling

const validateSdkEnv = (): void => {
  if (!process.env.TWENTY_API_URL || !process.env.TWENTY_APP_ACCESS_TOKEN) {
    throw new Error(
      'Missing env vars. Set TWENTY_API_URL and TWENTY_APP_ACCESS_TOKEN before calling SDK functions.',
    );
  }
};

validateSdkEnv();

Type guard

const hasSdkEnvVars = (): boolean => {
  const url = process.env.TWENTY_API_URL;
  const token = process.env.TWENTY_APP_ACCESS_TOKEN;
  return typeof url === 'string' && url.length > 0 &&
    typeof token === 'string' && token.length > 0;
};

Try / catch

try {
  const conn = await getConnection(id);
} catch (error) {
  if (error instanceof Error && error.message.includes('requires the app runtime env vars')) {
    console.error('Set TWENTY_API_URL and TWENTY_APP_ACCESS_TOKEN in your environment.');
    process.exit(1);
  }
  throw error;
}

Prevention

Load environment variables (dotenv) before any SDK logic function call.
Add a startup validation check for required env vars in your app's bootstrap.
Document TWENTY_API_URL and TWENTY_APP_ACCESS_TOKEN in your project's .env.example.

When it happens

Trigger: Calling any SDK logic function (getConnection, listConnections, etc.) without TWENTY_API_URL or TWENTY_APP_ACCESS_TOKEN set in process.env. The function checks both vars and throws before making any network request if either is absent.

Common situations: Running SDK logic functions in a local dev environment without loading .env. Deploying the app without setting the required environment variables. The env var names were changed or misconfigured. Using a different env var name by mistake (e.g. TWENTY_API_URL_V2 instead of TWENTY_API_URL).

Related errors

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