vitessio/vitess · error

err

Error message

err

What it means

During DELETE query planning, Vitess calls SemTable.GetChildForeignKeysForTable to discover child foreign-key constraints pointing at the delete target. If semantic analysis cannot resolve the target table (because the table was not found, is ambiguous, or the delete targets a table it cannot resolve to a single TableSet), the returned error is re-panicked so planning aborts. The error text is whatever the semantic layer produced, typically a 'table not found' or ambiguous-table message.

Source

Thrown at go/vt/vtgate/planbuilder/operators/delete.go:84

	// We check if delete with input plan is required. DML with input planning is generally
	// slower, because it does a selection and then creates a delete statement wherein we have to
	// list all the primary key values.
	if deleteWithInputPlanningRequired(childFks, deleteStmt) {
		return createDeleteWithInputOp(ctx, deleteStmt)
	}

	delClone := sqlparser.Clone(deleteStmt)
	var vTbl *vindexes.BaseTable
	op, vTbl = createDeleteOperator(ctx, deleteStmt)

	if deleteStmt.Comments != nil {
		op = newLockAndComment(op, deleteStmt.Comments, sqlparser.NoLock)
	}

	var err error
	childFks, err = ctx.SemTable.GetChildForeignKeysForTable(deleteStmt.Targets[0])
	if err != nil {
		panic(err)
	}
	// If there are no foreign key constraints, then we don't need to do anything special.
	if len(childFks) == 0 {
		return op
	}

	return createFkCascadeOpForDelete(ctx, op, delClone, childFks, vTbl)
}

func deleteWithInputPlanningRequired(childFks []vindexes.ChildFKInfo, deleteStmt *sqlparser.Delete) bool {
	if len(deleteStmt.Targets) > 1 {
		return true
	}
	// If there are no foreign keys, we don't need to use delete with input.
	if len(childFks) == 0 {
		return false
	}
	// Limit requires delete with input.

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Verify the DELETE targets a single, correctly keyspace-qualified table that exists in the vschema (SHOW VSCHEMA TABLES / check vschema JSON).
2. Simplify the DELETE: remove multi-table targets and run one DELETE per table.
3. Check the underlying error message in the panic for 'not found' vs 'ambiguous' and fix the table name or qualification accordingly.
4. If the table exists and the query is simple, capture the exact SQL and file an issue with the Vitess version — this is likely a planner bug.

Example fix

// before (failing)
DELETE FROM unknown_table WHERE id = 1;

// after (fix: qualify and ensure table is in vschema)
DELETE FROM commerce.orders WHERE id = 1;

// before issuing DELETE in app code
if !keyspaceHasTable(keyspace, "orders") {
    return fmt.Errorf("table %s.%s not found in vschema", keyspace, "orders")
}
if strings.Contains(strings.ToLower(sql), "delete") && countDeleteTargets(sql) > 1 {
    return errors.New("split multi-table deletes into single-table statements")
}

func tableExistsInVschema(t *sqlparser.TableName, vs map[string]interface{}) bool {
    return vs[t.Qualifier.String()+"."+t.Name.String()] != nil || vs[t.Name.String()] != nil
}

// Vitess returns panics as errors to clients; handle on the client
res, err := vtgateExec(ctx, sql)
if err != nil {
    if strings.Contains(err.Error(), "not found") {
        return recoverMissingTable(err) // verify name/vschema, then retry
    }
    return err
}

When it happens

Trigger: DELETE on a table whose target cannot be resolved by the semantic table during createOperatorFromDelete, e.g. DELETE against a non-existent/unqualified table that fails resolution, or after GetTargetTableSetForTableName succeeded earlier but GetChildForeignKeysForTable can't map deleteStmt.Targets[0] to table info.

Common situations: Running a DELETE with a multi-table or aliased target that semantic analysis resolved inconsistently; keyspace/table naming mistakes in the DELETE statement; querying a table removed from the vschema while sessions still reference it; hitting an internal planner bug where targets and table-set bookkeeping disagree.

Related errors

• VT13001
• VT09015
• VT12001
• VT12002
• err

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