hasura/graphql-engine · error

failed to reload metadata: %w

Error message

failed to reload metadata: %w

What it means

The `metadata reload` command asks the server to reload its metadata from its datastore, then runs the operation (o.run()) with a spinner. This error means the reload call itself failed — the server rejected the request, could not reload, or the connection failed. Note reload executes server-side: it re-reads the server's own metadata, not your local file.

Source

Thrown at cli/commands/metadata_reload.go:59

		},
	}

	return metadataReloadCmd
}

type MetadataReloadOptions struct {
	EC *cli.ExecutionContext
}

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

	o.EC.Spin("Reloading metadata...")
	err := o.run()
	o.EC.Spinner.Stop()

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

	o.EC.Logger.Info("Metadata reloaded")
	icListOpts := &metadataInconsistencyListOptions{
		EC: o.EC,
	}

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

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

View on GitHub (pinned to 724551b9ae)

Solutions

1. Check the wrapped error for the exact server response (auth vs internal error)
2. Verify the server's datastore connectivity from the server's perspective (server logs)
3. Confirm admin secret permissions include metadata reload
4. If reload consistently fails, restart the server and retry, or re-apply a known-good metadata file

Example fix

# before
hasura metadata reload  # failed to reload metadata
# after
# check server logs for reload errors, then:
hasura metadata reload

// confirm server is healthy before reload
resp, err := http.Get(endpoint + "/healthz")
if err != nil || resp.StatusCode != 200 {
  return errors.New("server unhealthy; reload likely to fail")
}

if err := reloadCmd.Execute(); err != nil {
  if strings.Contains(err.Error(), "failed to reload metadata") {
    // inspect server logs, verify datastore connectivity, retry after delay
  }
}

When it happens

Trigger: Running `metadata reload` when the server's reload_metadata API call errors: auth failure, network error, server unable to reload because its datastore is unreachable, or a server bug during reload.

Common situations: Reloading after applying metadata when the server's backing datastore connection is broken; insufficient permissions; server in a bad state where reload triggers an internal error; running reload against a read-only or paused instance.

Related errors

• failed to drop inconsistent metadata: %w
• failed to list inconsistent metadata: %w
• failed to read metadata status: %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/16ee941873fc23cd. Report an issue: GitHub.