vitessio/vitess · error

Foreign key found

Error message

Foreign key found

What it means

ErrForeignKeyFound signals that onlineddl schema validation discovered a FOREIGN KEY constraint in a statement where foreign keys are not allowed. validateWalk and onlineDDLStatementSanity reject foreign keys because online DDL (gh-ost/online-schema-change migrations) cannot safely handle them under the configured migration setup.

Source

Thrown at go/vt/schemadiff/onlineddl.go:31

See the License for the specific language governing permissions and
limitations under the License.
*/

package schemadiff

import (
	"errors"
	"fmt"
	"math"
	"sort"
	"strings"

	"vitess.io/vitess/go/mysql/capabilities"
	"vitess.io/vitess/go/vt/sqlparser"
)

var (
	ErrForeignKeyFound = errors.New("Foreign key found")

	copyAlgorithm = sqlparser.AlgorithmValue(sqlparser.CopyStr)
)

const (
	maxConstraintNameLength = 64
)

type ConstraintType int

const (
	UnknownConstraintType ConstraintType = iota
	CheckConstraintType
	ForeignKeyConstraintType
)

var constraintIndicatorMap = map[int]string{
	int(CheckConstraintType):      "chk",

View on GitHub (pinned to 01a25a7d17)

Solutions

1. Remove the FOREIGN KEY constraint from the statement, or run it as plain (non-online) DDL
2. Enable foreign key support for Online DDL in thevtctl/vttablet configuration if your setup supports it
3. Apply the FK in a separate migration step after the online migration completes

Example fix

// before
ALTER TABLE orders ADD CONSTRAINT fk_customer FOREIGN KEY (customer_id) REFERENCES customers(id) -- ErrForeignKeyFound under online DDL
// after
ALTER TABLE orders ADD COLUMN customer_id INT -- run FK add separately or via direct DDL

stmt, err := sqlparser.Parse(alterSQL)
_ = sqlparser.Walk(func(node sqlparser.SQLNode) (kontinue bool, err error) {
	if ct, ok := node.(*sqlparser.CreateTable); ok {
		for _, c := range ct.TableSpec.Constraints {
			if c.Check == nil { return false, fmt.Errorf("foreign key present: %s", c.Name) }
		}
	}
	return true, nil
}, stmt)

if err != nil {
	if errors.Is(err, schemadiff.ErrForeignKeyFound) {
		// reroute as non-online DDL or strip FK constraints
	}
}

When it happens

Trigger: Submitting an ALTER/CREATE with a FOREIGN KEY through Online DDL while FK support is disabled; validating a CREATE TABLE containing FOREIGN KEY constraints via validateAndEditCreateTableStatement.

Common situations: Migrating legacy schemas that rely on FKs into Vitess Online DDL; clusters with --enable-external-foreign-keys disabled or MySQL flavors/capabilities lacking FK support for online migrations.

Related errors

• Foreign key found
• source and target columns must be of same length
• vindex is in write-only mode
• can't rebuild serving keyspace while a migration is on going
• Error generating OnlineDDL query: %+v

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