iflytek/astron-agent · error · CustomException

PG_SQL_REQUEST_ERROR

PG_SQL_REQUEST_ERROR

Error message

err code {background_json.get('code')}, reason {background_json.get('message')}, sid {background_json.get('sid')}

What it means

The PostgreSQL backend service responded with a JSON body whose `code` field is non-zero, indicating the backend rejected or failed the request. `exec_dml` wraps the backend's `code`, `message` and `sid` into a PG_SQL_REQUEST_ERROR so callers get the upstream reason and trace id.

Solutions

  1. Read the `reason`/`sid` in the message and look up the sid in the PostgreSQL backend service logs to find the root cause.
  2. Validate the generated SQL and parameters before calling exec_dml (use the node's generate_dml to inspect the compiled statement).
  3. Check backend service health and its database connectivity (credentials, network) — most non-zero codes are backend-side failures.
  4. Retry only for transient backend errors after confirming the request payload is valid.

Example fix

null
Defensive patterns

Strategy: try-catch

Try / catch

try:
    result = client.exec_dml(...)
except CustomException as e:
    if "err code" in str(e):
        sid = extract_sid(str(e))  # parse sid for backend log lookup
        log.error("PGSQL backend rejected request", sid=sid, detail=str(e))
    raise

Prevention

When it happens

Trigger: Calling `exec_dml` where the HTTP call succeeds (200) but the response body has `code != 0`, e.g. backend SQL execution failed, invalid session (sid), or backend-internal error.

Common situations: Backend service returning business errors like SQL syntax rejection, permission denied on the target table, backend timeout, or backend service degraded; debugging via the `sid` in the message against backend logs.

Related errors

AI-assisted analysis of iflytek/astron-agent@5e758547a8 (2026-09-12). Data as JSON: /api/errors/154e8c90805a831d. Report an issue: GitHub.

Appendix: source

Thrown at core/workflow/engine/nodes/pgsql/pgsql_client.py:128

                        # Log execution time and response for monitoring
                        await request_span.add_info_events_async(
                            {"cost_time": f"{(time.time() - start_time) * 1000}"}
                        )
                        await request_span.add_info_events_async(
                            {
                                "response": json.dumps(
                                    background_json, ensure_ascii=False
                                )
                            }
                        )
                        # Check for service-level errors in response
                        if background_json.get("code") != 0:
                            msg = (
                                f"err code {background_json.get('code')}, "
                                f"reason {background_json.get('message')}, sid {background_json.get('sid')}"
                            )
                            request_span.add_error_event(msg)
                            raise CustomException(
                                err_code=CodeEnum.PG_SQL_REQUEST_ERROR,
                                err_msg=f"{msg}",
                            )
                        return background_json
            except CustomException as e:
                # Re-raise custom exceptions as-is
                raise e
            except Exception as e:
                # Handle unexpected errors during request execution
                err = str(e)
                request_span.add_error_event(err)
                raise CustomException(
                    err_code=CodeEnum.PG_SQL_REQUEST_ERROR,
                    err_msg=f"Database POST request failed: {err}",
                    cause_error=f"Database POST request failed: {err}",
                ) from e

    def payload(self) -> Dict[str, Any]:

View on GitHub (pinned to 5e758547a8)