hasura/graphql-engine · error

cannot set catalog state: %w

Error message

cannot set catalog state: %w

What it means

CopyState successfully fetched the catalog state but failed persisting it back with IsStateCopyCompleted=true via statestore.NewCLICatalogState(...).Set(...) (a v1metadata replace_metadata-style call).

Source

Thrown at cli/internal/scripts/update-project-v3.go:436

		statestore.NewCLICatalogState(ec.APIClient.V1Metadata),
	)
	if err := dstSettingsStore.PrepareSettingsDriver(); err != nil {
		return errors.E(op, err)
	}

	err = statestore.CopySettingsState(srcSettingsStore, dstSettingsStore)
	if err != nil {
		return errors.E(op, err)
	}

	cliState, err := statestore.NewCLICatalogState(ec.APIClient.V1Metadata).Get()
	if err != nil {
		return errors.E(op, fmt.Errorf("error while fetching catalog state: %w", err))
	}

	cliState.IsStateCopyCompleted = true
	if _, err := statestore.NewCLICatalogState(ec.APIClient.V1Metadata).Set(*cliState); err != nil {
		return errors.E(op, fmt.Errorf("cannot set catalog state: %w", err))
	}

	return nil
}

func CheckIfUpdateToConfigV3IsRequired(ec *cli.ExecutionContext) error {
	var op errors.Op = "scripts.CheckIfUpdateToConfigV3IsRequired"
	// see if an update to config V3 is necessary
	if ec.Config.Version <= cli.V1 && ec.HasMetadataV3 {
		ec.Logger.Info("config v1 is deprecated from v1.4")

		return errors.E(
			op,
			fmt.Errorf(
				"%s",
				"please upgrade your project to a newer version.\nuse "+color.New(color.FgCyan).
					SprintFunc()(
					"hasura scripts update-project-v2",

View on GitHub (pinned to 724551b9ae)

Solutions

1. Retry the update script — the state copy is idempotent-ish (Get then Set)
2. Check server connectivity and admin secret, then re-run
3. Inspect server logs for the rejected metadata write and fix the reported cause
4. If state is corrupted, follow docs to reset cli_state in hdb_catalog before retrying

for attempt := 0; attempt < 3; attempt++ {
    if err := scripts.CopyState(ec); err == nil { break } else if !strings.Contains(err.Error(), "cannot set catalog state") { return err }
    time.Sleep(time.Second * time.Duration(attempt+1))
}

When it happens

Trigger: The Set API call errors: server rejects the metadata, times out, or disconnects between the Get and Set calls of the state copy step.

Common situations: Transient network drop mid-upgrade, admin secret rotated between calls, server restarting, or corrupted state metadata that the server refuses to write.

Related errors

• error while fetching catalog state: %w
• pulling latest actions codegen files from internet failed: %
• unable to fetch introspection schema: %w
• error in fetching introspection schema: %w
• setting up codegen-assets repo failed (this is required for

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