hasura/graphql-engine · error

exporting metadata from server: %w

Error message

exporting metadata from server: %w

What it means

Raised by the `metadata export` command when the call to the server's ExportMetadata API (v1Metadata.ExportMetadata) fails. This is the first step of export: fetching the current metadata document from the server. Any transport error, auth error, or server-side error during that HTTP request is wrapped and reported with this message.

Source

Thrown at cli/commands/metadata_handlers.go:320

}

func (m *metadataModeYAMLHandler) Diff(o *MetadataDiffOptions) error {
	var op errors.Op = "commands.metadataModeYAMLHandler.Diff"

	err := diff(o, DifftypeYAML)
	if err != nil {
		return errors.E(op, err)
	}

	return nil
}

func export(o *MetadataExportOptions, mode cli.MetadataMode) error {
	var op errors.Op = "commands.export"

	metadata, err := ec.APIClient.V1Metadata.ExportMetadata()
	if err != nil {
		return errors.E(op, fmt.Errorf("exporting metadata from server: %w", err))
	}

	var metadataBytes []byte

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

	if mode == cli.MetadataModeYAML {
		metadataBytes, err = metadatautil.JSONToYAML(metadataBytes)
		if err != nil {
			return errors.E(op, fmt.Errorf("parsing metadata to yaml: %w", err))
		}
	}

	err = os.WriteFile(o.EC.MetadataFile, metadataBytes, os.ModePerm)
	if err != nil {

View on GitHub (pinned to 724551b9ae)

Solutions

1. Verify the endpoint URL and admin secret are correct for the target server (check config file and env overrides)
2. Test basic connectivity: curl the server's healthz/v1 metadata endpoint with the same credentials
3. Check server logs for the corresponding request failure (5xx, auth rejection)
4. Ensure the CLI version matches a server version that supports the v1 metadata export API

Example fix

# before
hasura metadata export --endpoint https://wrong-host/v1  # exporting metadata from server: ...
# after
hasura metadata export --endpoint https://correct-host --admin-secret $ADMIN_SECRET

// pre-flight check before export
req, _ := http.NewRequest("GET", endpoint+"/healthz", nil)
resp, err := http.DefaultClient.Do(req)
if err != nil || resp.StatusCode >= 500 {
  return errors.New("server unreachable, aborting export")
}

if err := export(opts, mode); err != nil {
  if isRetryable(err) { // network/5xx
    time.Sleep(backoff)
    return export(opts, mode)
  }
  return err
}

When it happens

Trigger: Running `metadata export` when the HTTP request to /v1metadata or /v1/metadata (export_metadata) fails: network unreachable, 401/403 from a bad admin secret, 500 from the server, TLS failures, or wrong endpoint configuration.

Common situations: Incorrect --endpoint or --admin-secret flags; expired or missing admin secret in config or env vars; server behind a proxy that blocks the request; CLI pointing at the wrong environment (e.g. dev endpoint that is down); server version not supporting the metadata API.

Related errors

• reading metadata from response: %w
• writing metadata to file: %w
• error building project metadata: %w
• parsing metadata to yaml: %w
• reading metadata file: %w

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