hasura/graphql-engine · error

error while fetching catalog state: %w

Error message

error while fetching catalog state: %w

What it means

CopyState, part of the v3 upgrade flow, failed to read the CLI catalog state via statestore.NewCLICatalogState(ec.APIClient.V1Metadata).Get() — i.e. fetching the hdb_catalog 'cli_state' metadata row from the Hasura server failed.

Source

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

	if err := srcSettingsStore.PrepareSettingsDriver(); err != nil {
		return errors.E(op, err)
	}

	dstSettingsStore := settings.NewStateStoreCatalog(
		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,

View on GitHub (pinned to 724551b9ae)

Solutions

1. Verify the Hasura server is running and the endpoint/admin secret in config are correct
2. Check server logs for the failed v1metadata request and resolve the API error
3. Retry the update script once connectivity is restored
4. Ensure server version supports config v3 state APIs (>= 1.4 series)

if err := ec.APIClient.V1MetadataCommon; err != nil { /* verify server reachable */ }
// preflight: hit /healthz before running the state copy
if resp, err := http.Get(endpoint + "/healthz"); err != nil || resp.StatusCode != 200 {
    return fmt.Errorf("server not healthy")
}

if err := scripts.CopyState(ec); err != nil {
    if strings.Contains(err.Error(), "fetching catalog state") { /* wait, verify endpoint/admin secret, retry */ }
}

When it happens

Trigger: Running the state-copy step of `hasura scripts update-project-v3` (or CopyState directly) when the Hasura GraphQL engine is unreachable, the API errors, or the metadata API request fails.

Common situations: Server not running / wrong endpoint in config, auth (admin secret) mismatch, network issues, or an incompatible server version lacking the statestore metadata APIs.

Related errors

• cannot set 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/05c1f69d561e7627. Report an issue: GitHub.