iflytek/astron-agent · error · ValueError

MASDK_POLARIS_URL environment variable is not configured

Error message

MASDK_POLARIS_URL environment variable is not configured

What it means

MASDKServiceFactory.create requires the MASDK_POLARIS_URL environment variable for Polaris service discovery and raises ValueError when it is unset or empty. This is the first (line 41) check of five in the factory's env-var validation.

Solutions

Set MASDK_POLARIS_URL (e.g. http://polaris:8080) in the workflow service environment and restart.
Check docker-compose.yml / Helm values / .env for the workflow container specifically.
Confirm with `docker exec <container> env | grep MASDK` that the variable is actually injected.
If MASDK is optional, avoid instantiating MASDKService when Polaris is not configured.

Example fix

// before (docker-compose.yml)
  workflow:
    environment: []
// after
  workflow:
    environment:
      - MASDK_POLARIS_URL=http://polaris:8080

Defensive patterns

Strategy: validation

Validate before calling

import os
assert os.getenv("MASDK_POLARIS_URL"), "MASDK_POLARIS_URL must be set before creating MASDKService"

Type guard

def masdk_env_ready() -> bool:
    return bool(os.getenv("MASDK_POLARIS_URL"))

Try / catch

try:
    service = service_manager.create_service(MASDKService)
except ValueError as e:
    logger.error(f"MASDK misconfigured: {e}")
    raise

Prevention

Document MASDK_POLARIS_URL in deployment templates (.env.example, Helm values).
Validate required env vars at service startup with fail-fast checks.
Use a config schema (pydantic Settings) to require MASDK_* fields.
Verify with `env | grep MASDK` inside the running container.

When it happens

Trigger: os.getenv("MASDK_POLARIS_URL") returns None or "" when MASDKService is created through the service manager with the MASDK factory.

Common situations: Deploying the workflow service without the MASDK block in .env / docker-compose / Helm values; the variable only defined in a different service's env file; enabling an agent feature that touches MASDK without provisioning Polaris.

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/b13f8c4053304529. Report an issue: GitHub.

Appendix: source

Thrown at core/workflow/extensions/middleware/masdk/factory.py:41

    def create(self) -> MASDKService:
        """
        Create a new MASDKService instance with configuration from environment variables.

        Reads the following environment variables:
        - MASDK_POLARIS_URL: Polaris service discovery URL
        - MASDK_POLARIS_PROJECT: Polaris project name
        - MASDK_POLARIS_GROUP: Polaris service group
        - MASDK_POLARIS_SERVICE: Polaris service name
        - MASDK_POLARIS_VERSION: Polaris service version
        - MASDK_CHANNEL: MASDK channel configuration

        :return: Configured MASDKService instance
        :raises ValueError: If required environment variables are not set
        """
        # Read Polaris service discovery configuration from environment variables
        polaris_url = os.getenv("MASDK_POLARIS_URL")
        if not polaris_url:
            raise ValueError("MASDK_POLARIS_URL environment variable is not configured")

        polaris_project = os.getenv("MASDK_POLARIS_PROJECT")
        if not polaris_url:
            raise ValueError("MASDK_POLARIS_URL environment variable is not configured")

        polaris_group = os.getenv("MASDK_POLARIS_GROUP")
        if not polaris_url:
            raise ValueError("MASDK_POLARIS_URL environment variable is not configured")

        polaris_service = os.getenv("MASDK_POLARIS_SERVICE")
        if not polaris_url:
            raise ValueError("MASDK_POLARIS_URL environment variable is not configured")

        polaris_version = os.getenv("MASDK_POLARIS_VERSION")
        if not polaris_url:
            raise ValueError("MASDK_POLARIS_URL environment variable is not configured")

        # Configure channel list with fallback to empty string

View on GitHub (pinned to 5e758547a8)