hasura/graphql-engine · error

reading metadata failed: %w

Error message

reading metadata failed: %w

What it means

After a successful server export, the CLI reads the entire metadata response body with io.ReadAll; failure during that read (connection reset, stream closed prematurely, reader error) produces this error. The metadata was fetched but could not be fully transferred to memory.

Source

Thrown at cli/commands/metadata_export.go:115

	}

	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. Retry the export — transient stream breaks often resolve themselves
2. If metadata is very large, increase proxy/load-balancer read timeouts between you and the server
3. Check server logs for OOM/crash during export; a large schema may need server resource bumps
4. Export from a network path closer to the server to rule out intermediary cuts

# Shell: size check via curl to anticipate large payloads
curl -s -o /dev/null -w '%{size_download}\n' -H "X-Hasura-Admin-Secret: $SECRET" \
  "$ENDPOINT/v1/metadata" -d '{"type":"export_metadata"}'

// Go: retry reads broken by transient network cuts
var b []byte
var err error
for i := 0; i < 3; i++ {
  b, err = io.ReadAll(reader)
  if err == nil { break }
}

When it happens

Trigger: `hasura metadata export --output-format ...` where the HTTP response stream breaks mid-read: server closes connection early, network interruption between client and server, proxy timeouts on large metadata payloads.

Common situations: Large metadata payloads exceeding proxy/LB idle timeouts (504-style cuts), flaky connections to remote Hasura Cloud instances, or servers restarted mid-response.

Related errors

• writing output failed: %w
• failed to export metadata: %w
• determining database kind of '%s': %w
• determining database kind of '%s': %w
• reading metadata from response: %w

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