hasura/graphql-engine · error

applying metadata: %w

Error message

applying metadata: %w

What it means

This is the core server-side failure in metadata apply: the CLI successfully read and parsed local metadata, then called V2ReplaceMetadata on the Hasura server (with AllowInconsistentMetadata: true) and the server returned an error. The wrapped error text from the GraphQL API usually describes the real problem, e.g. unknown table, inconsistent objects, or permission denied.

Source

Thrown at cli/pkg/metadata/mode_handlers.go:265

		)
	}

	if p.ec.Config.Version == cli.V2 {
		r, err := cli.GetCommonMetadataOps(p.ec).
			ReplaceMetadata(bytes.NewReader(localMetadataBytes))
		if err != nil {
			return nil, errors.E(op, err)
		}

		return r, nil
	}

	r, err := p.ec.APIClient.V1Metadata.V2ReplaceMetadata(hasura.V2ReplaceMetadataArgs{
		AllowInconsistentMetadata: true,
		Metadata:                  metadata,
	})
	if err != nil {
		return nil, errors.E(op, fmt.Errorf("applying metadata: %w", err))
	}

	b := new(bytes.Buffer)
	if err := json.NewEncoder(b).Encode(r); err != nil {
		return nil, errors.E(op, fmt.Errorf("encoding json response from server: %w", err))
	}

	return b, nil
}

func export(p *ProjectMetadata, mode cli.MetadataMode) (io.Reader, error) {
	var op errors.Op = "metadata.export"

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

View on GitHub (pinned to 724551b9ae)

Solutions

1. Read the wrapped server error message — it names the offending object (table, relationship, action, etc.)
2. Ensure the target database schema matches the metadata (run/apply migrations first, then metadata)
3. Verify the server endpoint and admin secret/env vars used by the CLI are correct and the Hasura version is compatible with the metadata version
4. Remove or fix the inconsistent objects the server complains about, then re-apply

Example fix

# before
hasura metadata apply  # applying metadata for table "users" that target DB lacks
# after
hasura migrate apply     # create the schema first
hasura metadata apply

// Go: inspect errors.Is/As on the wrapped API error
if _, err := pm.Apply(ctx, mode); err != nil {
    var msg string
    if errors.As(err, &hasuraErr) { msg = hasuraErr.Message }
    // branch on 'inconsistent metadata' vs auth vs connectivity
}

When it happens

Trigger: Calling Apply when the metadata references database tables/relationships/permissions that do not exist on the target server's configured databases; when the Hasura version does not support fields present in the metadata; or when the endpoint/admin secret are wrong (auth errors surface here too since the request reached the API layer).

Common situations: Applying metadata exported from an environment whose database schema differs from the target; applying v2 metadata to an incompatible server version; missing env var substitutions so table names resolve incorrectly; wrong HASURA_GRAPHQL_ADMIN_SECRET causing 401 from the metadata API.

Related errors

• error fetching config from server: %w
• error fetching server config: %v
• cannot write metadata directory: %w
• cannot create metadata files: %w
• got error while getting the sources list : %w

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