Invalid table name format '{}'. For SQL Server CDC, you must

Error message

Invalid table name format '{}'. For SQL Server CDC, you must specify the schema name. Use 'schema.table' format (e.g., 'dbo.{}') or 'database.schema.table' format (e.g., '{}.dbo.{}').

What it means

RisingWave rejects a SQL Server CDC `CREATE TABLE ... WITH (table_name = ...)` whose external table name has no schema component. `derive_with_options_for_cdc_table` splits the name on '.' and expects exactly 2 parts ('schema.table') or 3 parts ('database.schema.table'); a bare table name (1 part) is rejected because SQL Server CDC requires a schema to locate the source table and to build a unique Debezium topic identifier. The message shows concrete examples using the connector's actual source database name.

Source

Thrown at src/frontend/src/handler/create_table.rs:1075

                                "The database name '{}' in FROM clause does not match the database name '{}' specified in source definition. \
                                 You can either use 'schema.table' format (recommended) or ensure the database name matches.",
                                db_name,
                                source_database_name
                            ).into());
                        }
                        (schema_name, table_name)
                    }
                    2 => {
                        // Format: schema.table (recommended)
                        // Database name is taken from source definition
                        let schema_name = parts[0];
                        let table_name = parts[1];
                        (schema_name, table_name)
                    }
                    1 => {
                        // Format: table only
                        // Reject with clear error message
                        return Err(anyhow!(
                            "Invalid table name format '{}'. For SQL Server CDC, you must specify the schema name. \
                             Use 'schema.table' format (e.g., 'dbo.{}') or 'database.schema.table' format (e.g., '{}.dbo.{}').",
                            external_table_name,
                            external_table_name,
                            source_database_name,
                            external_table_name
                        ).into());
                    }
                    _ => {
                        // Invalid format (4+ parts or empty)
                        return Err(anyhow!(
                            "Invalid table name format '{}'. Expected 'schema.table' or 'database.schema.table'.",
                            external_table_name
                        ).into());
                    }
                };

                // Insert schema and table names into connector properties

View on GitHub (pinned to 6469eb736d)

Solutions

Change the table_name/externaltables option to include the schema: 'dbo.customers'.
If a different database is needed, use the 3-part form 'mydb.dbo.customers'.
Verify the schema exists in the SQL Server database and that the CDC user has SELECT/CDC permissions on it.
If the name contains special characters, keep it as a single quoted option value; the split is on '.' so escaped dots are not supported.

Example fix

// before
WITH (
  connector = 'sqlserver-cdc',
  table_name = 'customers'
)
// after
WITH (
  connector = 'sqlserver-cdc',
  table_name = 'dbo.customers'
)

Defensive patterns

Strategy: validation

Validate before calling

function validateSqlServerCdcTableName(name) {
  const parts = name.split('.');
  return parts.length === 2 || parts.length === 3;
}
// validateSqlServerCdcTableName('dbo.customers') === true
// validateSqlServerCdcTableName('customers') === false -> fix before DDL

Type guard

const isQualified = (n) => typeof n === 'string' && [2, 3].includes(n.split('.').length) && n.split('.').every(p => p.length > 0);

Prevention

Always write SQL Server CDC table names fully schema-qualified ('dbo.xxx').
Centralize table-name construction in a helper that appends the schema when missing.
Add a lint/unit test on DDL generators that enforces 2- or 3-part names.

When it happens

Trigger: Running CREATE TABLE with connector = 'sqlserver-cdc' (or sqlserver) and an externaltables/table_name option like 'customers', 'dbo.customers' is fine, but 'customers' alone hits the 1-part branch at create_table.rs:1075.

Common situations: Users coming from Postgres CDC habits (where 'public.table' is sometimes assumed) omit the schema; copying a MySQL-style connection string that omits schema; scripts generating DDL from a table list without schema qualification.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

AI-assisted analysis of risingwavelabs/risingwave@6469eb736d (2026-09-11). Data as JSON: /api/errors/d02e2f8a10eff11c. Report an issue: GitHub.