cube-js/cube · error · UserError

Table names should be in <table> or <schema>.<table> format

Error message

Table names should be in <table> or <schema>.<table> format

What it means

Thrown by ScaffoldingSchema.resolveTableName() as the fall-through error when the table name string splits into something other than 1 or 2 dot-separated parts (e.g. 'a.b.c' three-part names, or empty/malformed names). Table names for scaffolding must be either '<table>' or '<schema>.<table>'.

Source

Thrown at packages/cubejs-schema-compiler/src/scaffolding/ScaffoldingSchema.ts:159

      this.resolveTableDefinition(tableName);
      return tableName;
    } else if (tableParts.length === 1 && typeof tableName === 'string') {
      const schema = Object.keys(this.dbSchema).find(
        (tableSchema) => this.dbSchema[tableSchema][tableName] ||
          this.dbSchema[tableSchema][inflection.tableize(tableName)]
      );
      if (!schema) {
        throw new UserError(`Can't find any table with '${tableName}' name`);
      }
      if (this.dbSchema[schema][tableName]) {
        return `${schema}.${tableName}`;
      }
      if (this.dbSchema[schema][inflection.tableize(tableName)]) {
        return `${schema}.${inflection.tableize(tableName)}`;
      }
    }

    throw new UserError(
      'Table names should be in <table> or <schema>.<table> format'
    );
  }

  public cubeDescriptors(tableNames: TableName[]): CubeDescriptor[] {
    const cubes = this.generateForTables(tableNames);

    function member(type: MemberType) {
      return (value: Omit<CubeDescriptorMember, 'memberType'>) => ({
        memberType: type,
        ...R.pick(['name', 'title', 'types', 'isPrimaryKey', 'included', 'isId'], value)
      });
    }

    return cubes.map((cube) => ({
      cube: cube.cube,
      tableName: cube.tableName,
      table: cube.table,

View on GitHub (pinned to 7d981676b3)

Solutions

1. Pass only '<table>' or '<schema>.<table>' — drop the database/catalog prefix (e.g. 'myschema.mytable' not 'mydb.myschema.mytable')
2. Ensure the connection is configured to the right database so the catalog part is unnecessary
3. Strip stray quotes, brackets, or whitespace from the table-name string before scaffolding
4. For BigQuery-style project.dataset.table, configure the project in the driver and use 'dataset.table'

Example fix

// before
scaffoldingTableNames: ["mydb.public.users"]
// after
scaffoldingTableNames: ["public.users"]

function assertTableNameFormat(name) {
  if (typeof name !== 'string') throw new Error('tableName must be a string or [schema, table] array');
  const parts = name.split('.').filter(Boolean);
  if (parts.length < 1 || parts.length > 2) {
    throw new Error(`'${name}' must be <table> or <schema>.<table>`);
  }
}

try {
  scaffoldingSchema.resolveTableName(tableName);
} catch (e) {
  if (e instanceof UserError && e.message.includes('<table> or <schema>.<table>')) {
    throw new Error('Drop the catalog/database prefix and pass schema.table');
  }
  throw e;
}

When it happens

Trigger: Calling resolveTableName (directly or via cubeDescriptors/generateForTables) with a TableName string like 'db.schema.table', a quoted multi-part name, an empty string, or an Array tableName whose parsed parts length > 2.

Common situations: Users paste fully-qualified names from other tools (catalog.schema.table in SQL Server / BigQuery project.dataset.table), pass JDBC-style identifiers, or accidentally include whitespace/quotes so the regex splits into 3+ parts.

Related errors

• Can't resolve '${m}'
• 'pre_aggregations' must be a sequence
• Can't find any table with '${tableName}' name
• Can't resolve ${tableName}: '${schema}' does not exist
• Can't resolve ${tableName}: '${table}' does not exist

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