{"record":{"id":"70b3e0f6b19c01ba","repo":"hasura/graphql-engine","slug":"error-setting-state-w","errorCode":null,"errorMessage":"error setting state: %w","messagePattern":"error setting state: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cli/migrate/util.go","lineNumber":280,"sourceCode":") (bool, error) {\n\tvar op errors.Op = \"migrate.copyStateToCatalogStateAPIIfRequired\"\n\t// if\n\t//\t\tthe project is in config v3\n\t// \t\tisStateCopyCompleted is false in catalog state\n\t//\t\thdb_catalog.schema_migrations is not empty\n\tif !ec.DisableAutoStateMigration && ec.Config.Version >= cli.V3 {\n\t\t// get cli catalog and check isStateCopyCompleted is false\n\t\tcs := statestore.NewCLICatalogState(ec.APIClient.V1Metadata)\n\n\t\tstate, err := cs.Get()\n\t\tif err != nil {\n\t\t\treturn false, errors.E(op, err)\n\t\t}\n\n\t\tmarkStateMigrationCompleted := func() error {\n\t\t\tstate.IsStateCopyCompleted = true\n\t\t\tif _, err := cs.Set(*state); err != nil {\n\t\t\t\treturn errors.E(op, fmt.Errorf(\"error setting state: %w\", err))\n\t\t\t}\n\n\t\t\treturn nil\n\t\t}\n\n\t\tif !state.IsStateCopyCompleted {\n\t\t\t// if control reaches this block we'll set IsStateCopyCompleted to true\n\t\t\t// this makes sure we only attempt to automatically do the state migration once\n\t\t\t// we'll leave it up to the user to correct the errors and use\n\t\t\t// scripts update-project-v3 --move-state-only to move state\n\t\t\t//\n\t\t\t// this will also make sure new config v3 projects will not repeatedly reach this block\n\t\t\t// for a example a user connecting a custom source named default\n\t\t\t// with no read permissions to other schemas ie we cannot access `hdb_catalog.schema_migrations`\n\t\t\t// in the first run it'll encounter an error but will also mark IsStateCopyCompleted to true\n\t\t\t// thereby not running this block again\n\n\t\t\t// check if hdb_catalog.schema_migrations exists","sourceCodeStart":262,"sourceCodeEnd":298,"githubUrl":"https://github.com/hasura/graphql-engine/blob/724551b9ae87845594ef0408cff0e50eb6c90dc5/cli/migrate/util.go#L262-L298","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Inspect the wrapped error for the server response (401/403 → fix admin secret; 500 → check server logs and metadata DB permissions)","Retry the command — the copy is idempotent and will attempt the flag again only if still unset","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","Ensure the Hasura server version supports catalog state (v2+ server with config v3)"],"exampleFix":"# before\nHASURA_GRAPHQL_ADMIN_SECRET: wrong   # error setting state: ... 401\n\n# after\nHASURA_GRAPHQL_ADMIN_SECRET: correct # retry the same migrate command","handlingStrategy":"retry","validationCode":"// Ensure credentials are valid before running v3 state migration\nif _, err := ec.APIClient.V1Metadata.Replace(...); err != nil {\n    return fmt.Errorf(\"metadata API not writable: %w\", err)\n}","typeGuard":null,"tryCatchPattern":"if _, err := migrate.NewMigrate(...); err != nil {\n    if strings.Contains(err.Error(), \"error setting state\") {\n        // fix admin secret/permissions, then retry; copy is idempotent\n    }\n}","preventionTips":["Run v2→v3 upgrades with a fresh, valid admin secret","Take a metadata DB backup before upgrading config version","Use `scripts update-project-v3 --move-state-only` if the flag stays unset"],"tags":["state-migration","config-v3","metadata-api","hasura"],"backgroundTag":"metadata-update-failed","analyzedSha":"724551b9ae87845594ef0408cff0e50eb6c90dc5","analyzedAt":"2026-08-28T07:32:55.105Z","schemaVersion":2},"datasetVersion":"2026-08-28T11:17:15.048Z"}