{"record":{"id":"26510b2694595a21","repo":"hasura/graphql-engine","slug":"run-sql-api-request-failed-d-26510b","errorCode":null,"errorMessage":"run_sql api request failed %d","messagePattern":"run_sql api request failed (.+?)","errorType":"http","errorClass":"errors.Error","httpStatus":null,"severity":"error","filePath":"cli/internal/hasura/sourceops/postgres/run_sql.go","lineNumber":35,"sourceCode":"\t\tType: \"run_sql\",\n\t\tArgs: input,\n\t}\n\n\tb := new(bytes.Buffer)\n\n\tresp, err := d.send(body, b)\n\tif err != nil {\n\t\treturn nil, errors.E(op, err)\n\t}\n\n\tif resp.StatusCode != http.StatusOK {\n\t\tif b.Len() > 0 {\n\t\t\treturn nil, errors.E(op, errors.KindHasuraAPI, b.String())\n\t\t} else {\n\t\t\treturn nil, errors.E(\n\t\t\t\top,\n\t\t\t\terrors.KindHasuraAPI,\n\t\t\t\tfmt.Errorf(\"run_sql api request failed %d\", resp.StatusCode),\n\t\t\t)\n\t\t}\n\t}\n\n\to := new(hasura.PGRunSQLOutput)\n\tif err = json.NewDecoder(b).Decode(o); err != nil {\n\t\treturn nil, errors.E(op, err)\n\t}\n\n\treturn o, nil\n}\n","sourceCodeStart":17,"sourceCodeEnd":47,"githubUrl":"https://github.com/hasura/graphql-engine/blob/724551b9ae87845594ef0408cff0e50eb6c90dc5/cli/internal/hasura/sourceops/postgres/run_sql.go#L17-L47","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Act on the embedded status: 401/403 → correct admin secret/endpoint; 5xx → check Postgres and Hasura logs and the source's connection","Grant the Hasura DB role privileges to create/alter the hdb_catalog schema or use a role with sufficient rights","Verify the Postgres connection directly (psql) with the same credentials","Repair metadata inconsistencies (export/inconsistent_objects) and ensure the source exists","If hdb_version schema is stale from an old version, follow the Hasura docs for migrating the catalog schema"],"exampleFix":"// before\nout, err := c.PGRunSQL(args)\nif err != nil { return err }\n\n// after\nout, err := c.PGRunSQL(args)\nif err != nil {\n  if strings.Contains(err.Error(), \"run_sql api request failed\") {\n    return fmt.Errorf(\"run_sql rejected (status in error); check admin secret, source config, hdb_catalog perms: %w\", err)\n  }\n  return err\n}","handlingStrategy":"try-catch","validationCode":"// Before migrations, verify the source and hdb_catalog permissions\n// psql \"$DB_URL\" -c 'CREATE SCHEMA IF NOT EXISTS hdb_catalog' should succeed with the configured role","typeGuard":"func isRunSQLError(err error) bool {\n  return err != nil && strings.Contains(err.Error(), \"run_sql api request failed\")\n}","tryCatchPattern":"out, err := c.PGRunSQL(args)\nif err != nil {\n  if isRunSQLError(err) {\n    // branch on embedded status: 401/403 → admin secret; 5xx → DB/source issue\n    return diagnoseRunSQL(err)\n  }\n  return err // may be a body-carrying Hasura error; inspect message\n}","preventionTips":["Pre-create hdb_catalog schema with the migration role","Verify DB credentials and reachability before migrate apply","Run hasura metadata inconsistency checks in CI"],"tags":["hasura","postgres","run-sql","migrations","http-status","api-error","go"],"backgroundTag":"hasura-metadata-api-error","analyzedSha":"724551b9ae87845594ef0408cff0e50eb6c90dc5","analyzedAt":"2026-08-28T07:32:55.105Z","schemaVersion":2},"datasetVersion":"2026-08-28T11:17:15.048Z"}