hasura/graphql-engine · error

failed to read metadata status: %w

Error message

failed to read metadata status: %w

What it means

The `metadata inconsistency status` command reads the server's consistency state via projectmetadata handler (opts.read). This error means reading that status failed — the handler's server query or metadata processing errored before a consistent/inconsistent verdict could be determined.

Source

Thrown at cli/commands/metadata_inconsistency_status.go:30

func newMetadataInconsistencyStatusCmd(ec *cli.ExecutionContext) *cobra.Command {
	opts := &metadataInconsistencyListOptions{
		EC: ec,
	}

	metadataInconsistencyStatusCmd := &cobra.Command{
		Use:          "status",
		Short:        "Check if the Hasura Metadata is inconsistent or not",
		Long:         "At times, when developing, the Hasura Metadata can become inconsistent. This command can be used to check if the Metadata is inconsistent or not.",
		SilenceUsage: true,
		RunE: func(cmd *cobra.Command, args []string) error {
			op := genOpName(cmd, "RunE")

			opts.EC.Spin("reading metadata status...")
			err := opts.read(projectmetadata.NewHandlerFromEC(ec))
			opts.EC.Spinner.Stop()

			if err != nil {
				return errors.E(op, fmt.Errorf("failed to read metadata status: %w", err))
			}

			if opts.isConsistent {
				opts.EC.Logger.Println("metadata is consistent")
			} else {
				return errors.E(
					op,
					"metadata is inconsistent, use 'hasura metadata ic list' command to see the inconsistent objects",
				)
			}

			return nil
		},
	}

	return metadataInconsistencyStatusCmd
}

View on GitHub (pinned to 724551b9ae)

Solutions

1. Verify server connectivity and admin secret (test with `metadata export`)
2. Check server logs for the failing consistency/metadata request
3. Retry — transient failures are common in polling scenarios
4. If parsing is the issue, upgrade the CLI to match the server's metadata API version

if _, err := cli.GetCommonMetadataOps(ec).ExportMetadata(); err != nil {
  return fmt.Errorf("server not ready for status read: %w", err)
}

if err := statusCmd.Execute(); err != nil {
  if strings.Contains(err.Error(), "failed to read metadata status") {
    // transient in polling setups: backoff and re-check
  }
}

When it happens

Trigger: Running `metadata inconsistency status` where read() fails: ExportMetadata or consistency-check API errors (network, auth, server 5xx), or the returned metadata cannot be parsed by the handler.

Common situations: Monitoring scripts polling consistency status against a server that intermittently fails; missing credentials in automated environments; server upgrade mid-poll causing API shape changes; corrupted server metadata breaking the handler's parsing.

Related errors

• failed to drop inconsistent metadata: %w
• failed to list inconsistent metadata: %w
• failed to reload metadata: %w
• failed to read metadata status: %w
• error building project metadata: %w

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