iflytek/astron-agent · error · CustomException

PG_SQL_NODE_EXECUTION_ERROR

PG_SQL_NODE_EXECUTION_ERROR

Error message

PGSQL_URL environment variable is not set

What it means

The PGSQL node client requires a PostgreSQL service URL to forward DML requests to. This error is thrown by `exec_dml` in pgsql_client.py when `self.config.url` is None, meaning the PGSQL_URL environment variable (or equivalent config) was never provided. The client refuses to proceed because it has no endpoint to send the SQL request to.

Solutions

  1. Set the PGSQL_URL environment variable for the workflow service (e.g. export PGSQL_URL=http://pgsql-proxy:8080) and restart the service.
  2. Add PGSQL_URL to the deployment config (docker-compose env / Helm values / k8s secret) so every replica has it.
  3. Verify at startup that PGSQL_URL is present (fail fast healthcheck) instead of discovering it at node execution time.
  4. Check config loading code (dotenv, configmap mount) to confirm the variable is actually read into the Pgsql config.

Example fix

// before (docker-compose.yml)
services:
  workflow:
    image: workflow:latest
// after (docker-compose.yml)
services:
  workflow:
    image: workflow:latest
    environment:
      - PGSQL_URL=http://pgsql-service:8080
Defensive patterns

Strategy: validation

Validate before calling

import os
if not os.getenv("PGSQL_URL"):
    raise RuntimeError("PGSQL_URL must be set before executing PGSQL nodes")

Type guard

def has_pgsql_url(config) -> bool:
    return bool(getattr(config, "url", None))

Try / catch

try:
    result = client.exec_dml(...)
except CustomException as e:
    if "PGSQL_URL" in str(e):
        # surface config error to operator, skip node
        ...
    raise

Prevention

When it happens

Trigger: Calling `PgsqlClient.exec_dml(...)` when the `PGSQL_URL` environment variable is unset, so the constructed config carries `url=None`.

Common situations: Deploying the workflow service without the PGSQL_URL env var in the container/manifest; docker-compose or Helm values missing the env entry; local dev run without a .env file; renaming the env var in a config refactor while old deployments still lack it.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

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

Appendix: source

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

        :param config: Configuration object containing database connection parameters
        """
        self.config = config

    async def exec_dml(self, span: Span) -> Dict[str, Any]:
        """Execute Data Manipulation Language (DML) statement.

        Sends a POST request to the PostgreSQL service with the configured
        DML statement and returns the execution result.

        :param span: Tracing span for monitoring and logging
        :return: Dictionary containing the execution result and response data
        :raises CustomException: If environment variable is not set or request fails
        """
        # Validate that the PostgreSQL service URL is configured
        url = self.config.url
        if url is None:
            raise CustomException(
                CodeEnum.PG_SQL_NODE_EXECUTION_ERROR,
                err_msg="PGSQL_URL environment variable is not set",
            )
        # Prepare request payload and headers
        payload = self.payload()
        headers = {
            "Content-Type": "application/json",
            "Authorization": f"Bearer ${self.config.apiKey}",
            "X-Consumer-Username": self.config.appId,
        }
        # Add space_id to payload if provided
        if self.config.spaceId:
            payload["space_id"] = self.config.spaceId
        # Start tracing span for request monitoring
        with span.start(
            func_name="exec_dml_request", add_source_function_name=True
        ) as request_span:
            # Log request details for tracing

View on GitHub (pinned to 5e758547a8)