hasura/graphql-engine · error · errors.Error

pg_dump request: %d %s

Error message

pg_dump request: %d 
%s

What it means

This error is returned by the pg_dump client's Send function in the Hasura CLI when the Hasura server responds to the /v1alpha1/pg_dump request with any HTTP status other than 200. It is wrapped with errors.KindHasuraAPI, so it represents a server-side rejection of the pg_dump API call rather than a transport failure. The message includes the HTTP status code and the raw response body, which usually contains the server's JSON error explaining the refusal (e.g. metadata inconsistent, permission denied, or unsupported operation).

Source

Thrown at cli/internal/hasura/pgdump/pgdump.go:55

	return resp, nil
}

func (c *Client) Send(request hasura.PGDumpRequest) (io.Reader, error) {
	var op errors.Op = "pgdump.Client.Send"

	responseBody := new(bytes.Buffer)

	response, err := c.send(request, responseBody)
	if err != nil {
		return nil, errors.E(op, err)
	}

	if response.StatusCode != http.StatusOK {
		return nil, errors.E(
			op,
			errors.KindHasuraAPI,
			fmt.Errorf("pg_dump request: %d \n%s", response.StatusCode, responseBody.String()),
		)
	}

	return responseBody, nil
}

View on GitHub (pinned to 724551b9ae)

Solutions

  1. Read the response body embedded in the message — it contains the server's actual error (path, permission, or metadata problem) and dictates the fix
  2. Verify HASURA_GRAPHQL_ADMIN_SECRET / --admin-secret matches the target server
  3. Confirm the Hasura server version supports pg_dump (v2 DDN / v1alpha1 pg_dump endpoint) by hitting the /v1/version endpoint
  4. Fix the server state: reconnect the source database and resolve metadata inconsistencies via the /v1/metadata endpoint before retrying
  5. Retry with a fresh CLI version matching your server generation if the endpoint returns 404

Example fix

// before
body, err := client.Send(req)
if err != nil {
  log.Fatalf("pg_dump failed: %v", err) // opaque
}

// after
body, err := client.Send(req)
if err != nil {
  var e hasura.ErrHasuraAPI
  if errors.As(err, &e) {
    log.Fatalf("pg_dump failed (HTTP %d): %s", e.StatusCode, e.Body)
  }
  log.Fatalf("pg_dump failed: %v", err)
}
Defensive patterns

Strategy: try-catch

Validate before calling

// Verify server reachability and admin secret before pg_dump
req, _ := http.NewRequest(http.MethodGet, endpoint+"/v1/version", nil)
req.Header.Set("X-Hasura-Admin-Secret", adminSecret)
resp, err := http.DefaultClient.Do(req)
if err != nil || resp.StatusCode != http.StatusOK {
  return fmt.Errorf("server not ready for pg_dump: %v / status %d", err, resp.StatusCode)
}

Type guard

func isHasuraAPIError(err error) bool {
  var e *errors.Error
  return errors.As(err, &e) && e.Kind() == errors.KindHasuraAPI
}

Try / catch

body, err := client.Send(req)
if err != nil {
  if isHasuraAPIError(err) {
    // status + body are embedded in err.Error(); parse and branch on 401/404/5xx
    log.Printf("pg_dump rejected by server: %v", err)
    return diagnose(err)
  }
  return err // transport failure
}

Prevention

When it happens

Trigger: Calling pg_dump.Send (used by 'hasura3 migrate apply / export' flows) against a Hasura instance that answers non-200: e.g. 401/403 when the admin secret is wrong or missing, 404 on server versions without the pg_dump API, 500 when the source database is unreachable or metadata is inconsistent, or 400 when the selected source/database options are invalid.

Common situations: Running CLI commands against a Hasura Cloud vs OSS server of a different version, an incorrect HASURA_GRAPHQL_ADMIN_SECRET in the environment or config, a disconnected or misconfigured database source in metadata, or an inconsistent metadata state on the server after failed migrations.

Related errors

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