iflytek/astron-agent · error · ValueError

Missing required environment variables for Alembic

Error message

Missing required environment variables for Alembic: {missing}

What it means

get_database_url builds the SQLAlchemy Alembic database URL from required MYSQL_* environment variables. It collects any of MYSQL_HOST, MYSQL_PORT, MYSQL_USER, MYSQL_PASSWORD, MYSQL_DB that are empty or unset and raises ValueError listing exactly which ones are missing, preventing Alembic from forming an invalid connection string.

Solutions

Export all five required variables (MYSQL_HOST, MYSQL_PORT, MYSQL_USER, MYSQL_PASSWORD, MYSQL_DB) in the shell or environment running alembic
Use `set -a; source .env; set +a` or `export $(grep -v '^#' .env | xargs)` before invoking alembic
In Docker Compose/CI, pass the variables via env_file or secrets instead of relying on the shell
Check the error message's `missing` list — it names the exact variables to add

Example fix

// before
$ alembic upgrade head
ValueError: Missing required environment variables for Alembic: MYSQL_PASSWORD, MYSQL_DB
// after
$ set -a; source ./mysql.env; set +a
$ alembic upgrade head   # proceeds with mysql+pymysql://user:***@host:3306/db

Defensive patterns

Strategy: validation

Validate before calling

import os
required = ['MYSQL_HOST','MYSQL_PORT','MYSQL_USER','MYSQL_PASSWORD','MYSQL_DB']
missing = [k for k in required if not os.getenv(k)]
if missing:
    raise SystemExit(f'Missing env vars for Alembic: {", ".join(missing)}')

Try / catch

try:
    subprocess.run(['alembic', 'upgrade', 'head'], check=True, env=env_with_mysql_vars)
except ValueError as e:
    print('Alembic env incomplete:', e)

Prevention

Always source the mysql env file before running alembic
Inject DB secrets via env_file/secrets in CI and containers, never rely on the interactive shell
Keep the five MYSQL_* variable names consistent across environments
Guard empty-string values — treat them as unset

When it happens

Trigger: Running `alembic upgrade head` (or any alembic command importing env.py) when one or more of MYSQL_HOST/MYSQL_PORT/MYSQL_USER/MYSQL_PASSWORD/MYSQL_DB are unset or empty in the process environment.

Common situations: Forgetting to source the .env file before running migrations; running alembic in CI without injecting the DB secrets; renamed variables between environments; empty-string values in a compose file that satisfy os.getenv but fail the truthiness check.

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

Appendix: source

Thrown at core/plugin/link/alembic/env.py:41

    host = os.getenv("MYSQL_HOST")
    port = os.getenv("MYSQL_PORT")
    user = os.getenv("MYSQL_USER")
    password = os.getenv("MYSQL_PASSWORD")
    db = os.getenv("MYSQL_DB")

    missing = [
        key
        for key, value in [
            ("MYSQL_HOST", host),
            ("MYSQL_PORT", port),
            ("MYSQL_USER", user),
            ("MYSQL_PASSWORD", password),
            ("MYSQL_DB", db),
        ]
        if not value
    ]
    if missing:
        raise ValueError(
            "Missing required environment variables for Alembic: " + ", ".join(missing)
        )

    return f"mysql+pymysql://{user}:{password}@{host}:{port}/{db}"


config.set_main_option("sqlalchemy.url", get_database_url())


def get_metadata():  # type: ignore[no-untyped-def]
    return SQLModel.metadata


def include_object(
    object: SchemaItem,
    name: str | None,
    type_: Literal[
        "schema",

View on GitHub (pinned to 5e758547a8)