ent/ent · error

universal id and increment start annotation are mutually exc

Error message

universal id and increment start annotation are mutually exclusive

What it means

Configuration-consistency guard while building the atlas schema state: universalID is the legacy global-unique-id mechanism (backed by the ent_type table) while IncrementStart is the newer annotation-based mechanism, and enabling both would double-allocate id ranges. The error fires when a.universalID is true and an entity carries a non-nil IncrementStart annotation. The offending input is the entity type whose schema mixes both mechanisms.

Source

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

			if et.Comment != "" {
				av.SetComment(et.Comment)
			}
			if err := a.aVColumns(et, av); err != nil {
				return nil, err
			}
			s.AddViews(av)
			continue
		}
		at := schema.NewTable(et.Name)
		if et.Comment != "" {
			at.SetComment(et.Comment)
		}
		a.sqlDialect.atTable(et, at)
		// universalID is the old implementation of the global unique id, relying on a table in the database.
		// The new implementation is based on annotations attached to the schema. Only one can be enabled.
		switch {
		case a.universalID && et.Annotation != nil && et.Annotation.IncrementStart != nil:
			return nil, errors.New("universal id and increment start annotation are mutually exclusive")
		case a.universalID && et.Name != TypeTable && len(et.PrimaryKey) == 1:
			r, err := a.pkRange(et)
			if err != nil {
				return nil, err
			}
			a.sqlDialect.atIncrementT(at, r)
		case et.Annotation != nil && et.Annotation.IncrementStart != nil:
			a.sqlDialect.atIncrementT(at, int64(*et.Annotation.IncrementStart))
		}
		if err := a.aColumns(et, at); err != nil {
			return nil, err
		}
		if err := a.aIndexes(et, at); err != nil {
			return nil, err
		}
		s.AddTables(at)
		byT[et] = at
	}

View on GitHub (pinned to 69d5d4deb1)

Solutions

1. Pick one mechanism: either disable universal IDs (drop the universal-id option) and keep the IncrementStart annotation, or remove the entgql/increment-start annotation and rely on universalID.
2. If multiple entities are involved, locate the offending one from the schema annotations before the error position.

When it happens

Trigger: Thrown at dialect/sql/schema/atlas.go:883 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/7cf64579d6b4c532. Report an issue: GitHub.