hasura/graphql-engine · error

error setting state: %w

Error message

error setting state: %w

What it means

During the automatic v2→v3 state migration (copyStateToCatalogStateAPIIfRequired), after moving migration state to the catalog-state API the CLI tries to flip IsStateCopyCompleted=true via the statestore Set call; failure to persist that flag raises 'error setting state'. The wrapped error is a Hasura metadata API failure.

Source

Thrown at cli/migrate/util.go:280

) (bool, error) {
	var op errors.Op = "migrate.copyStateToCatalogStateAPIIfRequired"
	// if
	//		the project is in config v3
	// 		isStateCopyCompleted is false in catalog state
	//		hdb_catalog.schema_migrations is not empty
	if !ec.DisableAutoStateMigration && ec.Config.Version >= cli.V3 {
		// get cli catalog and check isStateCopyCompleted is false
		cs := statestore.NewCLICatalogState(ec.APIClient.V1Metadata)

		state, err := cs.Get()
		if err != nil {
			return false, errors.E(op, err)
		}

		markStateMigrationCompleted := func() error {
			state.IsStateCopyCompleted = true
			if _, err := cs.Set(*state); err != nil {
				return errors.E(op, fmt.Errorf("error setting state: %w", err))
			}

			return nil
		}

		if !state.IsStateCopyCompleted {
			// if control reaches this block we'll set IsStateCopyCompleted to true
			// this makes sure we only attempt to automatically do the state migration once
			// we'll leave it up to the user to correct the errors and use
			// scripts update-project-v3 --move-state-only to move state
			//
			// this will also make sure new config v3 projects will not repeatedly reach this block
			// for a example a user connecting a custom source named default
			// with no read permissions to other schemas ie we cannot access `hdb_catalog.schema_migrations`
			// in the first run it'll encounter an error but will also mark IsStateCopyCompleted to true
			// thereby not running this block again

			// check if hdb_catalog.schema_migrations exists

View on GitHub (pinned to 724551b9ae)

Solutions

1. Inspect the wrapped error for the server response (401/403 → fix admin secret; 500 → check server logs and metadata DB permissions)
2. Retry the command — the copy is idempotent and will attempt the flag again only if still unset
3. If the state copy is already complete but the flag won't persist, run `hasura scripts update-project-v3 --move-state-only` as suggested by the CLI docs
4. Ensure the Hasura server version supports catalog state (v2+ server with config v3)

Example fix

# before
HASURA_GRAPHQL_ADMIN_SECRET: wrong   # error setting state: ... 401

# after
HASURA_GRAPHQL_ADMIN_SECRET: correct # retry the same migrate command

// Ensure credentials are valid before running v3 state migration
if _, err := ec.APIClient.V1Metadata.Replace(...); err != nil {
    return fmt.Errorf("metadata API not writable: %w", err)
}

if _, err := migrate.NewMigrate(...); err != nil {
    if strings.Contains(err.Error(), "error setting state") {
        // fix admin secret/permissions, then retry; copy is idempotent
    }
}

When it happens

Trigger: Running a config-v3 migrate/metadata command for the first time when the catalog_state metadata operation fails — e.g. the server rejects the request (bad admin secret, read-only metadata DB, permissions on hdb_catalog), after the state copy itself already ran.

Common situations: Upgrading a project from config v2 to v3 with a locked-down metadata database; expired/incorrect admin secret mid-operation; Hasura server version that doesn't support catalog state; network blip between CLI and server.

Related errors

• error fetching config from server: %w
• error fetching server config: %v
• error serving console: %w
• operation failed: %w
• unable to create directory: %w

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