hasura/graphql-engine · error

cannot reload metadata: %w

Error message

cannot reload metadata: %w

What it means

Thrown by the `hasura metadata reload` command when the GraphQL Engine server fails to process the metadata reload API call (POST /v1/metadata with reload_metadata). The underlying error from projectmetadata.Handler.ReloadMetadata is wrapped, so the root cause (network, auth, or server-side metadata inconsistency) is in the wrapped error chain.

Source

Thrown at cli/commands/metadata_reload.go:93

		icListOpts.EC.Logger.Warnln(
			"Metadata is inconsistent, use 'hasura metadata ic list' command to see the inconsistent objects",
		)
	}

	return nil
}

func (o *MetadataReloadOptions) run() error {
	var (
		op  errors.Op = "commands.MetadataReloadOptions.run"
		err error
	)

	metadataHandler := projectmetadata.NewHandlerFromEC(o.EC)

	_, err = metadataHandler.ReloadMetadata()
	if err != nil {
		return errors.E(op, fmt.Errorf("cannot reload metadata: %w", err))
	}

	return nil
}

View on GitHub (pinned to 724551b9ae)

Solutions

1. Verify the endpoint is reachable and the admin secret/env is correct (hasura metadata reload --endpoint ... --admin-secret ...)
2. Inspect the wrapped error text for the server's response (e.g. 'x-hasura-admin-secret missing')
3. Fix or `hasura metadata apply` a known-good metadata.json before reloading
4. Check server logs if the reload is rejected due to inconsistent metadata

Example fix

# before
hasura metadata reload
# after
hasura metadata reload --endpoint https://my-server.hasura.app --admin-secret "$HASURA_ADMIN_SECRET"

curl -sf -H "x-hasura-admin-secret: $SECRET" "$ENDPOINT/healthz" >/dev/null && echo ok

if err := cmd.Execute(); err != nil { if strings.Contains(err.Error(), "cannot reload metadata") { /* check connectivity/admin secret, then retry */ } }

When it happens

Trigger: Running `hasura metadata reload` against a server that is unreachable, returns 401/403 (admin secret mismatch), or has invalid/inconsistent metadata that the server cannot reload.

Common situations: Wrong HASURA_GRAPHQL_ADMIN_SECRET, pointing --endpoint at a stopped/local dev server, or server metadata referencing a dropped database/source so reload is rejected.

Related errors

• error getting actions file content: %w
• error in creating action: %w
• error in applying metadata: %w
• cannot export metadata from server: %w
• cue extraction error: %w

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