{"record":{"id":"9e8e24ad29d2a5a5","repo":"iflytek/astron-agent","slug":"alembic-ini-not-found-alembic-ini","errorCode":null,"errorMessage":"alembic.ini not found: {alembic_ini}","messagePattern":"alembic\\.ini not found: (.+?)","errorType":"console","errorClass":"FileNotFoundError","httpStatus":null,"severity":"error","filePath":"core/plugin/link/extensions/database_migration.py","lineNumber":71,"sourceCode":"            (const.MYSQL_PASSWORD_KEY, mysql_password),\n            (const.MYSQL_DB_KEY, mysql_db),\n        ]\n        if not value\n    ]\n    if missing_envs:\n        raise ValueError(\n            \"Missing required MySQL environment variables for migration: \"\n            f\"{', '.join(missing_envs)}\"\n        )\n\n\ndef _build_alembic_config(link_dir: Path) -> Config:\n    \"\"\"Build Alembic config from local link module files.\"\"\"\n    alembic_dir = link_dir / \"alembic\"\n    alembic_ini = link_dir / \"alembic.ini\"\n    if not alembic_ini.exists():\n        logging.error(\"alembic.ini not found: %s\", alembic_ini)\n        raise FileNotFoundError(f\"alembic.ini not found: {alembic_ini}\")\n\n    config = Config(str(alembic_ini))\n    config.set_main_option(\"script_location\", str(alembic_dir))\n    return config\n\n\ndef _get_or_create_redis_service() -> RedisService:\n    \"\"\"Get or create Redis service instance.\"\"\"\n    redis_service = get_redis_engine()\n    if redis_service is not None:\n        logging.info(\"redis_service is successfully got from get_redis_engine()\")\n        return redis_service\n\n    redis_addr = os.getenv(const.REDIS_CLUSTER_ADDR_KEY) or os.getenv(\n        const.REDIS_ADDR_KEY\n    )\n    redis_password = os.getenv(const.REDIS_PASSWORD_KEY)\n    if not redis_addr:","sourceCodeStart":53,"sourceCodeEnd":89,"githubUrl":"https://github.com/iflytek/astron-agent/blob/5e758547a83371a5a4b29dadf4ac03e8dd527635/core/plugin/link/extensions/database_migration.py#L53-L89","documentation":"_build_alembic_config constructs the Alembic Config from <link_dir>/alembic.ini. If the file does not exist on disk it logs the missing path and raises FileNotFoundError. The migration runner depends on Alembic's ini for script_location and DB URL plumbing, so it refuses to continue without it.","triggerScenarios":"Calling run_database_migration when the link module directory does not contain alembic.ini — e.g. the package was installed/packaged without the alembic directory, or link_dir points at the wrong path in the deployed image.","commonSituations":"Docker image or wheel built that excludes non-Python files (missing package_data / MANIFEST entries); running from a working directory where the relative link path resolves elsewhere; alembic.ini accidentally gitignored or deleted; partial checkout.","solutions":["Verify the file exists at the expected link_dir (the logged path in the error) and restore alembic.ini if deleted","Fix packaging so alembic.ini and the alembic/ directory ship with the module (package_data, MANIFEST.in, or Dockerfile COPY)","Correct the link_dir argument/path resolution so it points at the module directory containing alembic.ini","Pull the latest link module sources if the checkout is stale or partial"],"exampleFix":"// before (Dockerfile)\nCOPY core/plugin/link/*.py ./link/\n// after (Dockerfile)\nCOPY core/plugin/link/ ./link/   # includes alembic.ini and alembic/","handlingStrategy":"validation","validationCode":"from pathlib import Path\ndef ensure_alembic_files(link_dir: Path) -> bool:\n    return (link_dir / \"alembic.ini\").exists() and (link_dir / \"alembic\").is_dir()","typeGuard":null,"tryCatchPattern":"try:\n    run_database_migration(link_dir)\nexcept FileNotFoundError as e:\n    if \"alembic.ini\" in str(e):\n        sys.exit(f\"Deployment error: {e}\")\n    raise","preventionTips":["Ensure Dockerfiles COPY the whole link module directory, not just *.py","Declare alembic.ini/alembic in package_data or MANIFEST.in if packaged as a wheel","Don't gitignore alembic.ini; commit migration configs with the code","Smoke-test the packaged artifact (not just the source tree) in CI"],"tags":["alembic","migration","file-not-found","packaging"],"backgroundTag":"config-file-not-found","analyzedSha":"5e758547a83371a5a4b29dadf4ac03e8dd527635","analyzedAt":"2026-09-12T08:03:51.356Z","contentChangedAt":"2026-09-12T08:03:51.356Z","schemaVersion":2},"datasetVersion":"2026-09-19T12:17:13.211Z"}