hasura/graphql-engine · error · errors.Error

cockroach_run_sql api request failed %d

Error message

cockroach_run_sql api request failed %d

What it means

CockroachRunSQL returns this error when the Hasura server responds to the cockroach_run_sql metadata API call with a non-200 status code and an empty response body. With no server message to include, the CLI reports only the status code. The error is classified errors.KindHasuraAPI — the request reached Hasura but the run_sql execution was rejected.

Source

Thrown at cli/internal/hasura/sourceops/cockroach/run_sql.go:37

		Type: "cockroach_run_sql",
		Args: input,
	}

	b := new(bytes.Buffer)

	resp, err := s.send(body, b)
	if err != nil {
		return nil, errors.E(op, err)
	}

	if resp.StatusCode != http.StatusOK {
		if b.Len() > 0 {
			return nil, errors.E(op, errors.KindHasuraAPI, b.String())
		} else {
			return nil, errors.E(
				op,
				errors.KindHasuraAPI,
				fmt.Errorf("cockroach_run_sql api request failed %d", resp.StatusCode),
			)
		}
	}

	parsedResp := new(hasura.CockroachRunSQLOutput)
	if err = json.NewDecoder(b).Decode(parsedResp); err != nil {
		return nil, errors.E(op, err)
	}

	return parsedResp, nil
}

View on GitHub (pinned to 724551b9ae)

Solutions

  1. Map the embedded status to a cause: 401/403 → admin secret; 404 → source kind support; 5xx → server/DB logs
  2. Test the CockroachDB connection independently (cockroach sql with the same URL) to catch TLS/network/credential problems
  3. Run the CLI with --debug for the full HTTP round trip
  4. Verify the cockroach source in metadata and reload/fix inconsistencies
  5. Match CLI and Hasura server versions

Example fix

// before
out, err := c.CockroachRunSQL(args)
if err != nil { return err }

// after
out, err := c.CockroachRunSQL(args)
if err != nil {
  if strings.Contains(err.Error(), "cockroach_run_sql api request failed") {
    return fmt.Errorf("cockroach_run_sql rejected; check server/DB logs: %w", err)
  }
  return err
}
Defensive patterns

Strategy: try-catch

Validate before calling

// Verify CockroachDB reachability from the Hasura host first
// e.g. cockroach sql --url "$SAME_URL" -e 'SELECT 1' must succeed before run_sql flows

Type guard

func isEmptyBodyAPIError(err error) bool {
  return err != nil && strings.Contains(err.Error(), "api request failed")
}

Try / catch

out, err := c.CockroachRunSQL(args)
if err != nil {
  if isEmptyBodyAPIError(err) {
    return diagnoseFromStatus(err)
  }
  return err
}

Prevention

When it happens

Trigger: Calling cockroach_run_sql during migrations against a CockroachDB source where the server returns 401/403 (bad admin secret), 404 (cockroach source kind not registered/supported), or 5xx with an empty body (CockroachDB cluster unreachable, TLS/certificate failure, or invalid connection parameters).

Common situations: Misconfigured CockroachDB connection string (wrong port, missing sslmode/CA cert), expired DB credentials, wrong admin secret, server version without the cockroach backend, or a proxy stripping error bodies.

Related errors

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