iflytek/astron-agent · error · ValueError

Missing required MySQL environment variables for migration

Error message

Missing required MySQL environment variables for migration: {missing_envs}

What it means

The link plugin's database migration runner validates that all required MySQL environment variables (host, port, user, password, database) are present before invoking Alembic. _check_db_url collects the env keys whose values are empty/missing and raises a ValueError listing them. This is a fail-fast guard so the migration never runs against a partially configured database.

Solutions

Set all required MySQL env vars (host, port, user, password, db) in the environment or .env file before running migrations
Check deployment config (docker-compose env_file, Helm secrets) actually injects the MYSQL_* variables into the container
Source the correct env file in local/CI shells (e.g. `set -a; . .env; set +a`) before invoking the migration
Fix env var name mismatches between const.py keys and the actual exported variable names

Example fix

// before
# .env
MYSQL_HOST=
MYSQL_DB=link
// after
# .env
MYSQL_HOST=127.0.0.1
MYSQL_PORT=3306
MYSQL_USER=root
MYSQL_PASSWORD=secret
MYSQL_DB=link

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 MySQL env vars: {', '.join(missing)}")

Try / catch

try:
    run_database_migration()
except ValueError as e:
    if "Missing required MySQL" in str(e):
        sys.exit(f"Config error: {e}")
    raise

Prevention

Keep required env vars documented and validated at service startup
Use docker-compose env_file / Helm secrets so vars are injected consistently
Fail fast with the same _check_db_url check in CI before migrations
Watch for env key renames between releases and update deployment configs

When it happens

Trigger: Running run_database_migration (e.g. on service startup or a migration script) when any of the const.MYSQL_*_KEY environment variables — MYSQL_HOST, MYSQL_PORT, MYSQL_USER, MYSQL_PASSWORD, MYSQL_DB — is unset or set to an empty string.

Common situations: Deploying without the MySQL section of the .env / docker-compose / Helm values; renaming env vars in a new release so old deployments keep stale keys; running migrations locally without sourcing the env file; CI jobs missing secret injection.

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

Appendix: source

Thrown at core/plugin/link/extensions/database_migration.py:59

    mysql_host = os.getenv(const.MYSQL_HOST_KEY)
    mysql_port = os.getenv(const.MYSQL_PORT_KEY)
    mysql_user = os.getenv(const.MYSQL_USER_KEY)
    mysql_password = os.getenv(const.MYSQL_PASSWORD_KEY)
    mysql_db = os.getenv(const.MYSQL_DB_KEY)

    missing_envs = [
        key
        for key, value in [
            (const.MYSQL_HOST_KEY, mysql_host),
            (const.MYSQL_PORT_KEY, mysql_port),
            (const.MYSQL_USER_KEY, mysql_user),
            (const.MYSQL_PASSWORD_KEY, mysql_password),
            (const.MYSQL_DB_KEY, mysql_db),
        ]
        if not value
    ]
    if missing_envs:
        raise ValueError(
            "Missing required MySQL environment variables for migration: "
            f"{', '.join(missing_envs)}"
        )


def _build_alembic_config(link_dir: Path) -> Config:
    """Build Alembic config from local link module files."""
    alembic_dir = link_dir / "alembic"
    alembic_ini = link_dir / "alembic.ini"
    if not alembic_ini.exists():
        logging.error("alembic.ini not found: %s", alembic_ini)
        raise FileNotFoundError(f"alembic.ini not found: {alembic_ini}")

    config = Config(str(alembic_ini))
    config.set_main_option("script_location", str(alembic_dir))
    return config

View on GitHub (pinned to 5e758547a8)