iflytek/astron-agent · critical · ValueError

KAFKA_SERVERS environment variable is not configured…

Error message

KAFKA_SERVERS environment variable is not configured. Please set KAFKA_SERVERS with comma-separated broker addresses

What it means

Pydantic validator for the Kafka servers setting raises ValueError when KAFKA_SERVERS is empty after stripping, both when passed in and when read from the environment. The service cannot form a Kafka bootstrap connection without at least one broker address, so startup fails fast.

Solutions

1. Set KAFKA_SERVERS to a comma-separated broker list, e.g. KAFKA_SERVERS=kafka-1:9092,kafka-2:9092, and restart the service
2. Add the key to the .env / Polaris config used by the service and verify it is mounted into the container (docker inspect / kubectl describe)
3. Check the variable name spelling and that it is exported in the process environment (env | grep KAFKA)
4. Provide a sane default in the compose/helm values for dev environments

Example fix

// before
# .env
# KAFKA_SERVERS=
// after
# .env
KAFKA_SERVERS=kafka:9092

import os
servers = os.getenv("KAFKA_SERVERS", "")
if not servers.strip():
    raise ConfigError("KAFKA_SERVERS must be set to comma-separated broker addresses before startup")

try:
    settings = AppConfig()
except ValidationError as e:
    if "KAFKA_SERVERS" in str(e):
        logger.critical("KAFKA_SERVERS not configured; aborting startup")
    raise SystemExit(2)

When it happens

Trigger: Starting core/workflow without KAFKA_SERVERS set in the environment or .env/config file; KAFKA_SERVERS set to whitespace or an empty string; config loader (local/polaris) not exposing the variable so the validator's os.getenv fallback also returns ''.

Common situations: Fresh deployment where docker-compose .env was not copied; secrets/config not mounted in k8s; Polaris config missing the key for a new namespace; variable spelled KAFKA_BROKERS instead of KAFKA_SERVERS.

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

• RUN_MCP_PLUGIN_URL is not set
• LIST_MCP_PLUGIN_URL is not set
• RAGFLOW_BASE_URL not configured in environment variables
• Missing required MySQL environment variables for migration
• Redis address is not set in environment variables

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

Appendix: source

Thrown at core/workflow/configs/app_config.py:248

        description="Kafka operation timeout in seconds",
    )

    kafka_session_timeout: int = Field(
        default=int(os.getenv("KAFKA_SESSIONTIMEOUT", "30")),
        alias="KAFKA_SESSIONTIMEOUT",
        description="Kafka session timeout in seconds",
    )

    @field_validator("kafka_servers", mode="after")
    @classmethod
    def validate_kafka_servers(cls, v: str) -> str:
        """Validate and clean Kafka servers configuration."""
        if not v:
            v = os.getenv("KAFKA_SERVERS", "")

        v = v.strip()
        if not v:
            raise ValueError(
                "KAFKA_SERVERS environment variable is not configured. "
                "Please set KAFKA_SERVERS with comma-separated broker addresses"
            )

        return v


# The built-in LangChain/Pyodide executor is isolated by Deno and therefore does
# not require an external service or user-provided credentials.  Keep the
# resource defaults conservative so a fresh deployment can execute Code nodes
# without exposing the workflow process to untrusted Python code.
DEFAULT_CODE_EXECUTOR_TYPE = "langchain"
DEFAULT_CODE_EXEC_TIMEOUT_SEC = 10
MIN_CODE_EXEC_TIMEOUT_SEC = 1
MAX_CODE_EXEC_TIMEOUT_SEC = 600
DEFAULT_CODE_EXEC_MEMORY_LIMIT_MB = 256
MIN_CODE_EXEC_MEMORY_LIMIT_MB = 128
MAX_CODE_EXEC_MEMORY_LIMIT_MB = 2048

View on GitHub (pinned to 5e758547a8)