hasura/graphql-engine · error

error building project metadata: %w

Error message

error building project metadata: %w

What it means

This error occurs when the CLI's dry-run mode for `metadata apply` fails to build a JSON representation of the project's metadata. The BuildJSONMetadata call aggregates resource states (tables, relationships, functions, etc.) into a JSON document that would be applied, and any failure in that aggregation (server query failure, malformed resource state) surfaces here. It wraps the underlying error with %w so the root cause is visible in the chain.

Source

Thrown at cli/commands/metadata_handlers.go:100

		}

		if len(o.rawOutput) != 0 {
			// if not a dry run fetch metadata from and server and print it to stdout
			err := getMetadataFromServerAndWriteToStdoutByFormat(o.EC, rawOutputFormat(o.rawOutput))
			if err != nil {
				return errors.E(op, err)
			}

			return nil
		}

		return nil
	}

	if o.DryRun {
		projectMetadataJSON, err := metadataHandler.BuildJSONMetadata()
		if err != nil {
			return errors.E(op, fmt.Errorf("error building project metadata: %w", err))
		}

		if o.DryRun && len(o.rawOutput) == 0 {
			// ie users who probably expect old behaviour
			// 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(

View on GitHub (pinned to 724551b9ae)

Solutions

1. Verify server connectivity and credentials (endpoint URL, admin secret) and retry the dry-run
2. Inspect the wrapped error (err chain) to identify which resource or query failed during metadata aggregation
3. Check that the CLI version is compatible with the server version's metadata API
4. If the server metadata itself is broken, run `metadata inconsistency list` to diagnose and fix inconsistencies before dry-running

Example fix

# before
hasura metadata apply --dry-run  # fails: error building project metadata
# after
# verify connectivity first
hasura metadata export  # confirms API access works
hasura metadata apply --dry-run

// before dry-run, verify basic API access
if _, err := ec.APIClient.V1Metadata.ExportMetadata(); err != nil {
  return fmt.Errorf("server not ready for metadata operations: %w", err)
}
// then run dry-run apply

if err := opts.Apply(); err != nil {
  if strings.Contains(err.Error(), "error building project metadata") {
    // surface wrapped cause, check connectivity/permissions
  }
  return err
}

When it happens

Trigger: Running `metadata apply --dry-run` (o.DryRun == true) when metadataHandler.BuildJSONMetadata() returns an error — typically because a query to the server's metadata API failed, a tracked resource could not be resolved, or the assembled metadata graph failed validation.

Common situations: Running a dry-run apply against an unreachable or misconfigured server endpoint; using an admin secret that lacks metadata permissions; a server version that returns unexpected resource shapes; a corrupted/incomplete metadata state on the server.

Related errors

• displaying metadata failed: %w
• exporting metadata from server: %w
• reading metadata from response: %w
• writing metadata to file: %w
• reading metadata file: %w

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