hasura/graphql-engine · error

reading server metadata: %w

Error message

reading server metadata: %w

What it means

During `metadata diff` in YAML mode, the server's JSON metadata is read and then converted to YAML with metadatautil.JSONToYAML before comparison. This error means that read succeeded but the conversion failed — the server response was not the expected valid JSON document.

Source

Thrown at cli/commands/metadata_handlers.go:435

	return nil
}

func diff(o *MetadataDiffOptions, diffType DiffType) error {
	var op errors.Op = "commands.diff"
	if len(o.Args) > 0 {
		return errors.E(op, fmt.Errorf("expected 0 arguments, found: %v", o.Args))
	}

	serverMetadata, err := cli.GetCommonMetadataOps(o.EC).ExportMetadata()
	if err != nil {
		return errors.E(op, fmt.Errorf("exporting metadata from server: %w", err))
	}

	var serverMetadataBytes []byte

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

	if diffType == DifftypeYAML {
		serverMetadataBytes, err = metadatautil.JSONToYAML(serverMetadataBytes)
		if err != nil {
			return errors.E(op, fmt.Errorf("parsing server metadata as yaml: %w", err))
		}
	}

	localMetadataBytes, err := os.ReadFile(o.EC.MetadataFile)
	if err != nil {
		return errors.E(op, fmt.Errorf("reading local metadata: %w", err))
	}

	if err := printMyersDiff(
		string(serverMetadataBytes),
		string(localMetadataBytes),
		"server",

View on GitHub (pinned to 724551b9ae)

Solutions

1. Run `metadata export -o json` to inspect the raw server metadata and confirm it is valid JSON
2. Compare CLI and server versions; upgrade the CLI if the server is newer
3. If server metadata is corrupted, use `metadata inconsistency list` / `metadata reload` to repair server state
4. Retry to rule out transient truncation (proxy timeout on large payloads)

// validate server metadata is JSON before YAML diff
var v any
if err := json.Unmarshal(serverMetadataBytes, &v); err != nil {
  // fall back to JSON diff type
}

if err := diff(o, DifftypeYAML); err != nil {
  if strings.Contains(err.Error(), "parsing server metadata as yaml") {
    return diff(o, DifftypeJSON) // fallback
  }
}

When it happens

Trigger: `metadata diff` with YAML diff type where the server metadata bytes fail JSONToYAML: malformed/truncated server response, HTML error page returned with a 200, or unexpected JSON shapes.

Common situations: Server or intermediate proxy returning an error body that is not valid JSON; version mismatch where the server emits a metadata shape the CLI cannot convert; corrupted metadata state on the server.

Related errors

• parsing metadata to yaml: %w
• parsing server metadata as yaml: %w
• parsing yaml metadata to json: %w
• reading local metadata: %w
• parsing local yaml metadata as json: %w

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