What causes "invalid database name: %s" in vitessio/vitess?

Qualify the insert with the correct sidecar name: `insert into _vt.vreplication ...` (default).

invalid database name: %s

Error message

invalid database name: %s

What it means

buildInsertPlan validates that an INSERT statement targets the sidecar database (the configured sidecar name or the default `_vt`). An INSERT qualified with any other database name is rejected with `invalid database name: <qualifier>`.

Source

Thrown at go/vt/vttablet/tabletmanager/vreplication/controller_plan.go:176

	}
	if err != nil {
		return nil, err
	}
	plan.query = query
	return plan, nil
}

func buildInsertPlan(ins *sqlparser.Insert) (*controllerPlan, error) {
	// This should never happen.
	if ins == nil {
		return nil, errors.New("BUG: invalid nil INSERT statement found when building VReplication plan")
	}
	tableName, err := ins.Table.TableName()
	if err != nil {
		return nil, err
	}
	if tableName.Qualifier.String() != sidecar.GetName() && tableName.Qualifier.String() != sidecar.DefaultName {
		return nil, fmt.Errorf("invalid database name: %s", tableName.Qualifier.String())
	}
	switch tableName.Name.String() {
	case reshardingJournalTableName:
		return &controllerPlan{
			opcode: reshardingJournalQuery,
		}, nil
	case vreplicationTableName:
		// no-op
	default:
		return nil, fmt.Errorf("invalid table name: %s", tableName.Name.String())
	}
	if ins.Action != sqlparser.InsertAct {
		return nil, fmt.Errorf("unsupported construct: %v", sqlparser.String(ins))
	}
	if ins.Ignore {
		return nil, fmt.Errorf("unsupported construct: %v", sqlparser.String(ins))
	}
	if ins.Partitions != nil {

View on GitHub (pinned to 01a25a7d17)

Solutions

Qualify the insert with the correct sidecar name: `insert into _vt.vreplication ...` (default).
If a custom sidecar identifier is configured, use that identifier in the qualifier.
Omit the database qualifier and target the sidecar table by name through the engine's own connection.
Check the tablet's --sidecar-db-name-identifier flag to learn the expected qualifier.

Example fix

// before
insert into commerce.vreplication(id, workflow) values (1, 'w')
// after
insert into _vt.vreplication(id, workflow) values (1, 'w')

Defensive patterns

Strategy: validation

Validate before calling

func validSidecarQualifier(q string, sidecar string) bool {
    return q == sidecar || q == "_vt" || q == ""
}
// check before issuing: validSidecarQualifier(qualifierFromSQL(stmt), sidecar.GetName())

Try / catch

plan, err := buildInsertPlan(ins, sidecar)
if err != nil && strings.Contains(err.Error(), "invalid database name") {
    return vterrors.Errorf(vtrpcpb.Code_INVALID_ARGUMENT, "qualify inserts with the sidecar db (%s), not another schema", sidecar.GetName())
}

Prevention

Always qualify sidecar tables with `_vt` or the configured --sidecar-db-name-identifier.
Grep scripts for schema-qualified vreplication references after sidecar renames.
Keep generated SQL unqualified or generated from sidecar.GetName() at runtime.

When it happens

Trigger: An INSERT whose table qualifier is neither the configured sidecar identifier nor sidecar.DefaultName — e.g. `INSERT INTO myschema.vreplication VALUES ...` issued through the vreplication engine's exec path.

Common situations: Typing the unqualified/wrongly qualified sidecar table name in a VExec statement; sidecar table renamed via --sidecar-db-name-identifier while scripts still use the old name; copying queries written for a different schema.

Related errors

AI-assisted analysis of vitessio/vitess@01a25a7d17 (2026-09-01). Data as JSON: /api/errors/b0b3d535bca4e918. Report an issue: GitHub.