hasura/graphql-engine · error

failed to export metadata: %w

Error message

failed to export metadata: %w

What it means

getMetadataFromServerAndWriteToStdoutByFormat exports metadata from the Hasura server via the common metadata ops; any failure of that export call is wrapped as 'failed to export metadata'. The underlying cause is usually an HTTP-level or server-side failure (auth, connectivity, or the server rejecting the export_metadata request).

Source

Thrown at cli/commands/metadata_export.go:110

	}

	err := getMetadataModeHandler(o.EC.MetadataMode).Export(o)
	if err != nil {
		return errors.E(op, err)
	}

	return nil
}

func getMetadataFromServerAndWriteToStdoutByFormat(
	ec *cli.ExecutionContext,
	format rawOutputFormat,
) error {
	var op errors.Op = "commands.getMetadataFromServerAndWriteToStdoutByFormat"

	metadataReader, err := cli.GetCommonMetadataOps(ec).ExportMetadata()
	if err != nil {
		return errors.E(op, fmt.Errorf("failed to export metadata: %w", err))
	}

	jsonMetadata, err := io.ReadAll(metadataReader)
	if err != nil {
		return errors.E(op, fmt.Errorf("reading metadata failed: %w", err))
	}

	if err := writeByOutputFormat(ec.Stdout, jsonMetadata, format); err != nil {
		return errors.E(op, err)
	}

	return nil
}

View on GitHub (pinned to 724551b9ae)

Solutions

1. Verify endpoint and admin secret flags/config are correct and current
2. Confirm server reachability and health (curl <endpoint>/healthz)
3. Inspect the wrapped error for HTTP status codes to distinguish 401/403 auth from 5xx server errors
4. Align CLI version with server version and retry

# Shell: verify auth+reachability first
curl -fsS -H "X-Hasura-Admin-Secret: $SECRET" "$ENDPOINT/v1/metadata" \
  -d '{"type":"export_metadata"}' >/dev/null || { echo 'export precheck failed'; exit 1; }
hasura metadata export --output-format json

// Go: retry with backoff on transient export failures
var meta io.Reader
var err error
for i := 0; i < 3; i++ {
  meta, err = cli.GetCommonMetadataOps(ec).ExportMetadata()
  if err == nil { break }
  time.Sleep(time.Second * time.Duration(i+1))
}

When it happens

Trigger: Running `hasura metadata export --output-format json|yaml` (stdout mode) or code calling getMetadataFromServerAndWriteToStdoutByFormat when ExportMetadata fails: wrong admin secret, unreachable endpoint, server error on the export_metadata API.

Common situations: Expired/rotated admin secret, hasura cloud vs local endpoint confusion, server behind a proxy that mangles the API response, or CLI/server version incompatibility in the metadata API.

Related errors

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

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