hasura/graphql-engine · error

parsing migration version: %w

Error message

parsing migration version: %w

What it means

The catalog state store (migrations state kept in hdb_catalog as JSON) contains a migration version key that is not a valid base-10 uint64; strconv.ParseUint fails when building the version map.

Source

Thrown at cli/internal/statestore/migrations/catalogstate.go:117

func (m *CatalogStateStore) PrepareMigrationsStateStore(_ string) error {
	return nil
}

func (m *CatalogStateStore) GetVersions(database string) (map[uint64]bool, error) {
	var op errors.Op = "migrations.CatalogStateStore.GetVersions"

	state, err := m.getCLIState()
	if err != nil {
		return nil, errors.E(op, err)
	}

	versions := map[uint64]bool{}

	for version, dirty := range state.GetMigrationsByDatabase(database) {
		parsedVersion, err := strconv.ParseUint(version, 10, 64)
		if err != nil {
			return nil, errors.E(op, fmt.Errorf("parsing migration version: %w", err))
		}

		versions[parsedVersion] = dirty
	}

	return versions, nil
}

func (m *CatalogStateStore) SetVersions(database string, versions []statestore.Version) error {
	var op errors.Op = "migrations.CatalogStateStore.SetVersions"

	state, err := m.getCLIState()
	if err != nil {
		return errors.E(op, err)
	}

	for _, v := range versions {
		versionString := strconv.FormatInt(v.Version, 10)

View on GitHub (pinned to 724551b9ae)

Solutions

1. Inspect the migration state in hdb_catalog (e.g. the migrations table / cli_state rows) for non-numeric version keys
2. Fix or remove the offending entries so all versions are numeric strings
3. Retry the operation (migrate status / update-project-v3)
4. If caused by a server bug, upgrade the Hasura server and re-sync state

Example fix

-- before: state contains version "01_init"
SELECT * FROM hdb_catalog.hdb_version;
-- after: keep only numeric versions
DELETE FROM hdb_catalog.hdb_catalog_migration WHERE version !~ '^[0-9]+$';

for v := range versions {
    if _, err := strconv.ParseUint(v, 10, 64); err != nil {
        return fmt.Errorf("non-numeric migration version %q in state; clean hdb_catalog first", v)
    }
}

func isNumericVersion(s string) bool { _, err := strconv.ParseUint(s, 10, 64); return err == nil }

if _, err := store.GetVersions(db); err != nil {
    if strings.Contains(err.Error(), "parsing migration version") { /* query state table, remove non-numeric keys, retry */ }
}

When it happens

Trigger: Calling GetVersions on a CLICatalogState/migration state store where the server-stored migration state JSON has a non-numeric key (e.g. a named migration like '01_init' or corrupted/manual entry) instead of a numeric version string.

Common situations: Hand-edited hdb_catalog state, server bugs writing state, or tooling that stored named/timestamp-style versions incompatible with the numeric version contract.

Related errors

• operation failed: %w
• cannot write migration directory: %w
• applying migrations on source: %s: %w
• migrations on database '%s' of kind '%s' is not supported
• %w: error determining database kind for '%s', check if datab

AI-assisted analysis of hasura/graphql-engine@724551b9ae (2026-08-28). Data as JSON: /api/errors/1bd046d969128e98. Report an issue: GitHub.