hasura/graphql-engine · error

failed to clear metadata: %w

Error message

failed to clear metadata: %w

What it means

This error wraps any failure from the metadata clear Run operation after the 'Clearing metadata...' spinner stops. The wrapped error is the real diagnostic — typically an HTTP/API failure talking to the Hasura server's clear_metadata endpoint. The CLI has already successfully built the execution context and config at this point.

Source

Thrown at cli/commands/metadata_clear.go:44

  hasura metadata clear --admin-secret "<admin-secret>"

  # Clear metadata on a different Hasura instance:
  hasura metadata clear --endpoint "<endpoint>"`,
		SilenceUsage: true,
		RunE: func(cmd *cobra.Command, args []string) error {
			op := genOpName(cmd, "RunE")
			if cmd.CalledAs() == "reset" {
				opts.EC.Logger.Warn(
					"metadata reset command is deprecated, use metadata clear instead",
				)
			}

			opts.EC.Spin("Clearing metadata...")
			err := opts.Run()
			opts.EC.Spinner.Stop()

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

			opts.EC.Logger.Info("Metadata cleared")

			return nil
		},
	}

	return metadataResetCmd
}

type MetadataClearOptions struct {
	EC *cli.ExecutionContext
}

func (o *MetadataClearOptions) Run() error {
	var (
		op  errors.Op = "commands.MetadataClearOptions.Run"

View on GitHub (pinned to 724551b9ae)

Solutions

1. Verify the endpoint and admin secret: hasura metadata clear --endpoint <url> --admin-secret <secret>
2. Check the server is reachable: curl the /healthz endpoint of your Hasura server
3. Inspect the wrapped error for the HTTP status/body to distinguish auth (401) from connectivity failures
4. Update the CLI to match your server version: hasura update-cli or reinstall

# Shell: check server health before clearing
hasura metadata clear --dry-run 2>/dev/null || true
curl -fsS "$ENDPOINT/healthz" || { echo 'server down'; exit 1; }

// Go: retry transient server errors
var err error
for i := 0; i < 3; i++ {
  if err = opts.Run(); err == nil { break }
  time.Sleep(time.Duration(i+1) * time.Second)
}

When it happens

Trigger: Running `hasura metadata clear` when the request to the server fails: wrong or missing --endpoint/--admin-secret, server unreachable, TLS issues, or the server returning an error for the clear_metadata operation.

Common situations: Admin secret mismatch (401/403), pointing at a stale endpoint after server migration, local dev server not running, self-signed certs in HTTPS setups, or CLI-server version skew where the metadata API shape differs.

Related errors

• failed to export metadata: %w
• unable to fetch introspection schema: %w
• error in fetching introspection schema: %w
• applying data sources failed: %s
• cannot clear Metadata: %w

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