hasura/graphql-engine · error

exporting metadata from server: %w

Error message

exporting metadata from server: %w

What it means

Thrown by metadata export when the call to the Hasura server's ExportMetadata API fails before any metadata is read. This is a transport/API-level failure: unreachable server, authentication failure, or the server rejecting the export request. The wrapped error carries the HTTP/GraphQL details.

Source

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

	})
	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))
	}

	var metadataBytes []byte

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

	if mode == cli.MetadataModeYAML {
		metadataBytes, err = metadatautil.JSONToYAML(metadataBytes)
		if err != nil {
			return nil, errors.E(op, fmt.Errorf("parsing metadata to yaml: %w", err))
		}
	}

	return bytes.NewReader(metadataBytes), nil
}

View on GitHub (pinned to 724551b9ae)

Solutions

1. Check the wrapped error: connection refused means wrong endpoint/server down; 401 means fix the admin secret
2. Verify connectivity: curl $ENDPOINT/healthz from the same machine/CI runner
3. Set the correct --endpoint and --admin-secret (or env vars) and retry
4. For TLS failures with self-signed certs, use the appropriate flag/env to trust the CA or fix certificates

Example fix

# before
hasura metadata export  # exporting metadata from server: connection refused
# after
hasura metadata export --endpoint https://hasura.example.com --admin-secret $SECRET

resp, err := http.Get(endpoint + "/healthz")
if err != nil || resp.StatusCode != 200 {
    return fmt.Errorf("Hasura server not reachable at %s", endpoint)
}

if _, err := pm.Export(ctx, mode); err != nil {
    if strings.Contains(err.Error(), "exporting metadata from server") {
        // check connectivity/auth: wrapped error distinguishes refused vs 401
    }
}

When it happens

Trigger: Calling Export (hasura metadata export) with an incorrect endpoint, an unreachable Hasura instance, a missing/wrong admin secret (401), or a server whose metadata API errors out. Any network error or non-2xx response from /v1metadata surfaces here.

Common situations: Server not running or wrong --endpoint; HASURA_GRAPHQL_ADMIN_SECRET not set or wrong value in env/config; on-prem server behind a VPN/firewall from where the CLI runs; SSL/TLS certificate verification failures against self-signed endpoints.

Related errors

• cannot export metadata from server: %w
• unable to fetch introspection schema: %w
• error in fetching introspection schema: %w
• got error while getting the sources list : %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/3bf09f172ad4f206. Report an issue: GitHub.