hasura/graphql-engine · error

displaying metadata failed: %w

Error message

displaying metadata failed: %w

What it means

During a dry-run `metadata apply`, after the JSON metadata is successfully built, the CLI attempts to print it to stdout in the requested raw output format (JSON or YAML). This error means the built metadata could not be rendered/written in the chosen format — almost always because the metadata blob is not valid for the requested conversion (e.g. invalid JSON for a YAML conversion) or stdout is not writable.

Source

Thrown at cli/commands/metadata_handlers.go:123

			// show a warning about change in behaviour
			o.rawOutput = string(rawOutputFormatJSON)
			o.EC.Logger.Warn(
				"behaviour of --dry-run flag has changed from v2.0.0. It used to show a diff between metadata on server and local project",
			)
			o.EC.Logger.Warn(
				"new behaviour is to output local project metadata as JSON by default. The output format is configurable by -o flag eg: `hasura metadata apply --dry-run -o yaml`",
			)
			o.EC.Logger.Warn(
				"the old behaviour can be achieved using `hasura metadata diff` command",
			)
		}

		if err := writeByOutputFormat(
			o.EC.Stdout,
			projectMetadataJSON,
			rawOutputFormat(o.rawOutput),
		); err != nil {
			return errors.E(op, fmt.Errorf("displaying metadata failed: %w", err))
		}
	}

	return nil
}

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

	args := o.Args
	messageFormat := "Showing diff between %s and %s..."
	metadataHandler := projectmetadata.NewHandlerFromEC(o.EC)
	fromFriendlyName := "project"
	toFriendlyName := "server"
	fromDirectory, toDirectory := "", ""

	switch len(args) {
	case 0:

View on GitHub (pinned to 724551b9ae)

Solutions

1. Retry with the default JSON raw output format to see if the conversion is the culprit
2. Inspect the wrapped error to see whether it is a marshalling error or a write error
3. Avoid piping the dry-run output to consumers that close the pipe early (use a file redirect instead)
4. If metadata itself is malformed, export and inspect it with `metadata export` to locate the invalid structure

err := opts.Apply()
if err != nil && strings.Contains(err.Error(), "displaying metadata failed") {
  // fall back to JSON output or write to a file instead of stdout
}

When it happens

Trigger: `metadata apply --dry-run` with a raw output format where writeByOutputFormat fails: invalid JSON bytes being converted, a JSON-to-YAML conversion error, or a closed/unwritable stdout stream.

Common situations: Passing --raw-output yaml when the built metadata contains values that fail YAML marshalling; piping output to a closed pipe (e.g. `| head` causing SIGPIPE/EPIPE); server returning malformed JSON metadata.

Related errors

• error building project metadata: %w
• cannot write metadata directory: %w
• cannot create metadata files: %w
• writing output failed: %w
• output format '%v' is not supported. supported formats: %v,

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