hasura/graphql-engine · error · errors.Error

run_sql api request failed %d

Error message

run_sql api request failed %d

What it means

PGRunSQL returns this error when the Hasura server responds to the pg_run_sql (run_sql) metadata API call with a non-200 status and an empty response body, leaving only the HTTP status code for the message. It is tagged errors.KindHasuraAPI and is the primary failure mode for migration bookkeeping calls (InsertVersion, SetVersion, RemoveVersion, PrepareMigrationsStateStore) that use this function.

Source

Thrown at cli/internal/hasura/sourceops/postgres/run_sql.go:35

		Type: "run_sql",
		Args: input,
	}

	b := new(bytes.Buffer)

	resp, err := d.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("run_sql api request failed %d", resp.StatusCode),
			)
		}
	}

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

	return o, nil
}

View on GitHub (pinned to 724551b9ae)

Solutions

  1. Act on the embedded status: 401/403 → correct admin secret/endpoint; 5xx → check Postgres and Hasura logs and the source's connection
  2. Grant the Hasura DB role privileges to create/alter the hdb_catalog schema or use a role with sufficient rights
  3. Verify the Postgres connection directly (psql) with the same credentials
  4. Repair metadata inconsistencies (export/inconsistent_objects) and ensure the source exists
  5. If hdb_version schema is stale from an old version, follow the Hasura docs for migrating the catalog schema

Example fix

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

// after
out, err := c.PGRunSQL(args)
if err != nil {
  if strings.Contains(err.Error(), "run_sql api request failed") {
    return fmt.Errorf("run_sql rejected (status in error); check admin secret, source config, hdb_catalog perms: %w", err)
  }
  return err
}
Defensive patterns

Strategy: try-catch

Validate before calling

// Before migrations, verify the source and hdb_catalog permissions
// psql "$DB_URL" -c 'CREATE SCHEMA IF NOT EXISTS hdb_catalog' should succeed with the configured role

Type guard

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

Try / catch

out, err := c.PGRunSQL(args)
if err != nil {
  if isRunSQLError(err) {
    // branch on embedded status: 401/403 → admin secret; 5xx → DB/source issue
    return diagnoseRunSQL(err)
  }
  return err // may be a body-carrying Hasura error; inspect message
}

Prevention

When it happens

Trigger: During 'hasura migrate apply/status' the CLI issues run_sql calls to create/update the hdb_catalog.hdb_version table; the server returns non-200 with no body when the admin secret is wrong (401/403), the postgres source is missing/unreachable (5xx), the target database lacks permission to create the hdb_catalog schema, or metadata is inconsistent.

Common situations: Postgres URL with wrong password or unreachable host, limited DB role without CREATE schema privileges on hdb_catalog, wrong --admin-secret or --endpoint, pointing the CLI at a database that already has an incompatible hdb_version schema from an older Hasura version.

Related errors

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