{"record":{"id":"d69850158a981087","repo":"nocodb/nocodb","slug":"apikey-is-required-provide-it-in-the-constructor","errorCode":null,"errorMessage":"apiKey is required. Provide it in the constructor options or use NocoDB.configure().","messagePattern":"apiKey is required\\. Provide it in the constructor options or use NocoDB\\.configure\\(\\)\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/nocodb-sdk-v2/src/sdk/nocodb.ts","lineNumber":19,"sourceCode":"import { InternalApi } from './lib/Api.ts';\nimport type { InternalAPI, NocoDBOptions } from './types';\nimport { Workspace } from './workspace';\n\nclass NocoDB {\n  private static _endPointURL = 'https://app.nocodb.com';\n  private static _apiKey: string;\n  private readonly internalAPI: InternalAPI;\n\n  constructor(\n    options: NocoDBOptions = {\n      endPointURL: 'https://app.nocodb.com',\n    },\n  ) {\n    const endPointURL = options.endPointURL || NocoDB._endPointURL;\n    const apiKey = options.apiKey || NocoDB._apiKey;\n\n    if (!apiKey) {\n      throw new Error(\n        'apiKey is required. Provide it in the constructor options or use NocoDB.configure().',\n      );\n    }\n\n    this.internalAPI = new InternalApi({\n      baseURL: endPointURL,\n      headers: {\n        ['xc-token']: apiKey,\n      },\n    }).api;\n  }\n\n  static configure(options: NocoDBOptions): void {\n    if (!options) {\n      throw new Error(\n        'options is required. Provide it in the constructor options or use NocoDB.configure().',\n      );\n    }","sourceCodeStart":1,"sourceCodeEnd":37,"githubUrl":"https://github.com/nocodb/nocodb/blob/d3caaf4e890acf64bd49b788cf6dc32b7644c895/packages/nocodb-sdk-v2/src/sdk/nocodb.ts#L1-L37","documentation":"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.","triggerScenarios":"`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).","commonSituations":"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.","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."],"exampleFix":"// before\nconst db = new NocoDB({ endPointURL: 'https://my.nocodb.app' });\n// throws: apiKey is required...\n\n// after\nconst db = new NocoDB({\n  endPointURL: 'https://my.nocodb.app',\n  apiKey: process.env.NOCODB_API_KEY!,\n});","handlingStrategy":"validation","validationCode":"function resolveApiKey(opts?: { apiKey?: string }, staticKey?: string): string {\n  const key = opts?.apiKey || staticKey;\n  if (!key) throw new Error('NOCODB_API_KEY is not set; refusing to construct NocoDB client');\n  return key;\n}\n\nconst apiKey = resolveApiKey(options, process.env.NOCODB_API_KEY);\nconst db = new NocoDB({ apiKey, endPointURL });","typeGuard":"function hasApiKey(opts: unknown): opts is { apiKey: string } {\n  return !!opts && typeof (opts as any)?.apiKey === 'string' && (opts as any).apiKey.length > 0;\n}","tryCatchPattern":"let db: NocoDB;\ntry {\n  db = new NocoDB({ apiKey: process.env.NOCODB_API_KEY, endPointURL });\n} catch (err) {\n  if (err instanceof Error && /apiKey is required/.test(err.message)) {\n    throw new Error('NOCODB_API_KEY environment variable is not configured');\n  }\n  throw err;\n}","preventionTips":["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."],"tags":["sdk","configuration","auth","nocodb"],"backgroundTag":null,"analyzedSha":"d3caaf4e890acf64bd49b788cf6dc32b7644c895","analyzedAt":"2026-08-12T13:07:32.092Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}