ent/ent · error

unexpected fk %q column: %q

Error message

unexpected fk %q column: %q

What it means

Consistency guard while building desired-state foreign keys for the schema: for a foreign key on a table, the corresponding column could not be found on the table's desired-state representation built from the ent schema. It names the fk symbol and the missing column — meaning the schema's edge/field definitions are internally inconsistent (e.g. an edge references a column the schema no longer defines), typically a codegen or schema-definition problem.

Source

Thrown at dialect/sql/schema/atlas.go:915

			return nil, err
		}
		s.AddTables(at)
		byT[et] = at
	}
	for _, t1 := range tables {
		if t1.View {
			continue
		}
		t2 := byT[t1]
		for _, fk1 := range t1.ForeignKeys {
			fk2 := schema.NewForeignKey(fk1.Symbol).
				SetTable(t2).
				SetOnUpdate(schema.ReferenceOption(fk1.OnUpdate)).
				SetOnDelete(schema.ReferenceOption(fk1.OnDelete))
			for _, c1 := range fk1.Columns {
				c2, ok := t2.Column(c1.Name)
				if !ok {
					return nil, fmt.Errorf("unexpected fk %q column: %q", fk1.Symbol, c1.Name)
				}
				fk2.AddColumns(c2)
			}
			var refT *schema.Table
			for _, t2 := range sm[fk1.RefTable.Schema].Tables {
				if t2.Name == fk1.RefTable.Name {
					refT = t2
					break
				}
			}
			if refT == nil {
				return nil, fmt.Errorf("unexpected fk %q ref-table: %q", fk1.Symbol, fk1.RefTable.Name)
			}
			fk2.SetRefTable(refT)
			for _, c1 := range fk1.RefColumns {
				c2, ok := refT.Column(c1.Name)
				if !ok {
					return nil, fmt.Errorf("unexpected fk %q ref-column: %q", fk1.Symbol, c1.Name)

View on GitHub (pinned to 69d5d4deb1)

Solutions

1. Check the named foreign key's edge definition and ensure both endpoint columns/fields exist in the ent schema
2. Regenerate the code (go generate) so derived table definitions are in sync with the schema
3. If it persists, simplify/review recently changed edges and report a reproducible schema upstream

When it happens

Trigger: Thrown at dialect/sql/schema/atlas.go:915 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of ent/ent@69d5d4deb1 (2026-09-03). Data as JSON: /api/errors/dcb7104e6815893d. Report an issue: GitHub.