nocodb/nocodb · error · Error

apiKey is required. Provide it in the constructor options or

Error message

apiKey is required. Provide it in the constructor options or use NocoDB.configure().

What it means

Thrown by the NocoDB SDK v2 constructor (packages/nocodb-sdk-v2) when neither the per-instance options.apiKey nor the static NocoDB._apiKey (set via NocoDB.configure) is present. The SDK requires an xc-token for every request, so it fails fast at construction rather than emitting 401s later. endPointURL defaults to https://app.nocodb.com, so only the key is mandatory.

Source

Thrown at packages/nocodb-sdk-v2/src/sdk/nocodb.ts:19

import { InternalApi } from './lib/Api.ts';
import type { InternalAPI, NocoDBOptions } from './types';
import { Workspace } from './workspace';

class NocoDB {
  private static _endPointURL = 'https://app.nocodb.com';
  private static _apiKey: string;
  private readonly internalAPI: InternalAPI;

  constructor(
    options: NocoDBOptions = {
      endPointURL: 'https://app.nocodb.com',
    },
  ) {
    const endPointURL = options.endPointURL || NocoDB._endPointURL;
    const apiKey = options.apiKey || NocoDB._apiKey;

    if (!apiKey) {
      throw new Error(
        'apiKey is required. Provide it in the constructor options or use NocoDB.configure().',
      );
    }

    this.internalAPI = new InternalApi({
      baseURL: endPointURL,
      headers: {
        ['xc-token']: apiKey,
      },
    }).api;
  }

  static configure(options: NocoDBOptions): void {
    if (!options) {
      throw new Error(
        'options is required. Provide it in the constructor options or use NocoDB.configure().',
      );
    }

View on GitHub (pinned to d3caaf4e89)

Solutions

Pass the apiKey in the constructor: new NocoDB({ apiKey: process.env.NOCODB_API_KEY }).
Or call NocoDB.configure({ apiKey }) once at process startup, then `new NocoDB()` will inherit it.
If using a self-hosted instance, also pass endPointURL alongside the apiKey.
Guard the value: throw a clear app-level error if process.env.NOCODB_API_KEY is missing, rather than letting the SDK throw.

Example fix

// before
const db = new NocoDB({ endPointURL: 'https://my.nocodb.app' });
// throws: apiKey is required...

// after
const db = new NocoDB({
  endPointURL: 'https://my.nocodb.app',
  apiKey: process.env.NOCODB_API_KEY!,
});

Defensive patterns

Strategy: validation

Validate before calling

function resolveApiKey(opts?: { apiKey?: string }, staticKey?: string): string {
  const key = opts?.apiKey || staticKey;
  if (!key) throw new Error('NOCODB_API_KEY is not set; refusing to construct NocoDB client');
  return key;
}

const apiKey = resolveApiKey(options, process.env.NOCODB_API_KEY);
const db = new NocoDB({ apiKey, endPointURL });

Type guard

function hasApiKey(opts: unknown): opts is { apiKey: string } {
  return !!opts && typeof (opts as any)?.apiKey === 'string' && (opts as any).apiKey.length > 0;
}

Try / catch

let db: NocoDB;
try {
  db = new NocoDB({ apiKey: process.env.NOCODB_API_KEY, endPointURL });
} catch (err) {
  if (err instanceof Error && /apiKey is required/.test(err.message)) {
    throw new Error('NOCODB_API_KEY environment variable is not configured');
  }
  throw err;
}

Prevention

Assert process.env.NOCODB_API_KEY at process startup, before constructing clients.
Centralize NocoDB client construction in one factory so misconfiguration fails once, clearly.
Use NocoDB.configure() once at boot in long-running services.

When it happens

Trigger: `new NocoDB()` or `new NocoDB({ endPointURL })` without an apiKey in the options and without a prior NocoDB.configure({ apiKey }) call. Also when options.apiKey is an empty string (falsy).

Common situations: Env var (e.g. NOCODB_API_KEY) not loaded before constructing the client; tests that build a NocoDB client without configuring; copy-paste of example code that omitted the apiKey line; SDK v1 → v2 migration where the constructor signature changed.

Related errors

AI-assisted analysis of nocodb/nocodb@d3caaf4e89 (2026-08-12). Data as JSON: /api/errors/d69850158a981087. Report an issue: GitHub.