What causes "SERVICE_PORT_KEY is not set" in iflytek/astron-agent?

Set SERVICE_PORT_KEY (the env var name it maps to, e.g. SERVICE_PORT) to a numeric port like 8000 before starting the service

iflytek/astron-agent · error · ValueError

SERVICE_PORT_KEY is not set

Error message

SERVICE_PORT_KEY is not set

What it means

start_uvicorn reads the port from the environment via const.SERVICE_PORT_KEY and refuses to start the Uvicorn server if it is unset or empty, raising ValueError. This avoids uvicorn receiving port=None and gives an actionable message at startup.

Solutions

Set SERVICE_PORT_KEY (the env var name it maps to, e.g. SERVICE_PORT) to a numeric port like 8000 before starting the service
Load the service's .env file in the startup shell or container env (env_file in compose, env in k8s spec)
Confirm the const.SERVICE_PORT_KEY constant matches the variable actually defined in your environment
Optionally default the port in code (e.g. os.getenv(key, '8000')) if a default is acceptable

Example fix

// before
$ python -m app.start_server
ValueError: SERVICE_PORT_KEY is not set
// after
$ export SERVICE_PORT=8080
$ python -m app.start_server   # uvicorn starts on 0.0.0.0:8080

Defensive patterns

Strategy: validation

Validate before calling

import os
port = os.getenv('SERVICE_PORT')
assert port and port.isdigit(), 'SERVICE_PORT must be set to a numeric port'

Try / catch

try:
    start()
except ValueError as e:
    logger.error('Startup aborted: %s — set SERVICE_PORT and retry', e)
    sys.exit(1)

Prevention

Define SERVICE_PORT in the container/compose env_file
Give a sane default (e.g. 8000) when a default port is acceptable
Document required env vars in the service README
Verify required vars in an entrypoint pre-check script

When it happens

Trigger: Calling start() / start_uvicorn() without SERVICE_PORT_KEY present in the environment — e.g. the service entrypoint is run with no exported port variable or an empty-string value.

Common situations: Launching the link service container without setting the port env var; renaming SERVICE_PORT_KEY's actual key name in config; running the app locally without loading the .env; empty value in deployment manifest causing the falsy check to fire.

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

Appendix: source

Thrown at core/plugin/link/app/start_server.py:121

            asyncio.run(setup_watchdog())
        except (ModuleNotFoundError, ImportError):
            pass
        except Exception as e:
            print(f"[Service] ⚠️  gateway watchdog setup exception:{str(e)}")

    @staticmethod
    def start_uvicorn() -> None:
        """
        Start the Uvicorn ASGI server with configuration loaded from environment
        variables.

        This method creates and starts a Uvicorn server instance using configuration
        parameters such as host, port, worker count, reload settings, and WebSocket
        ping intervals retrieved from environment variables.
        """
        service_port = os.getenv(const.SERVICE_PORT_KEY)
        if not service_port:
            raise ValueError("SERVICE_PORT_KEY is not set")
        uvicorn_config = uvicorn.Config(
            app=spark_link_app(),
            host="0.0.0.0",
            port=int(service_port),
            workers=20,
            reload=False,
            log_config=None,
        )
        uvicorn_server = uvicorn.Server(uvicorn_config)
        uvicorn_server.run()


def spark_link_app() -> FastAPI:
    """
    Create Spark Link app.

    Returns:
        FastAPI: The configured FastAPI application instance

View on GitHub (pinned to 5e758547a8)