cube-js/cube · error · Error

options.checkAuth must be a function

Error message

options.checkAuth must be a function

What it means

registerInterface requires a checkAuth function used to authenticate REST API requests through the native interface. If it is missing or not callable, authentication cannot be performed, so the registration is rejected.

Solutions

1. Provide a checkAuth function, e.g. async (req, authorization) => ({ password: authorization }).
2. Reuse your existing api-gateway checkAuth implementation and pass it into the options.
3. Verify the function reference is defined at the time registerInterface is called (no hoisting/import issues).

Example fix

// before
await registerInterface({ contextToApiScopes, checkSqlAuth, meta, stream });

// after
await registerInterface({
  contextToApiScopes,
  checkAuth: async (req, authorization) => ({ password: authorization }),
  checkSqlAuth, meta, stream
});

if (typeof options.checkAuth !== 'function') {
  throw new Error('options.checkAuth must be provided as a function');
}

function hasCheckAuth(o) {
  return typeof o?.checkAuth === 'function';
}

try {
  await registerInterface(options);
} catch (e) {
  if (e.message === 'options.checkAuth must be a function') {
    console.error('Provide checkAuth: async (req, authorization) => ({ password: authorization }).');
  } else throw e;
}

When it happens

Trigger: Calling registerInterface() with an options object whose checkAuth property is absent, null, or not a function.

Common situations: Omitting checkAuth while porting an existing Cube config to the native interface; renaming the auth handler but not updating this wiring; using a JWT-only config that assumed a default handler.

Related errors

• options.checkSqlAuth must be a function
• options.contextToApiScopes must be a function
• options.meta must be a function
• options.stream must be a function
• Argument options must be an object

AI-assisted analysis of cube-js/cube@7d981676b3 (2026-09-02). Data as JSON: /api/errors/42e202d6e0fe4eb2. Report an issue: GitHub.

Appendix: source

Thrown at packages/cubejs-backend-native/js/index.ts:392

export const isFallbackBuild = (): boolean => {
  const native = loadNative();
  return native.isFallbackBuild();
};

export type SqlInterfaceInstance = { __typename: 'sqlinterfaceinstance' };

export const registerInterface = async (options: SQLInterfaceOptions): Promise<SqlInterfaceInstance> => {
  if (typeof options !== 'object' && options == null) {
    throw new Error('Argument options must be an object');
  }

  if (typeof options.contextToApiScopes !== 'function') {
    throw new Error('options.contextToApiScopes must be a function');
  }

  if (typeof options.checkAuth !== 'function') {
    throw new Error('options.checkAuth must be a function');
  }

  if (typeof options.checkSqlAuth !== 'function') {
    throw new Error('options.checkSqlAuth must be a function');
  }

  if (typeof options.meta !== 'function') {
    throw new Error('options.meta must be a function');
  }

  if (typeof options.stream !== 'function') {
    throw new Error('options.stream must be a function');
  }

  if (typeof options.sqlApiLoad !== 'function') {
    throw new Error('options.sqlApiLoad must be a function');
  }

View on GitHub (pinned to 7d981676b3)