{"record":{"id":"cc75ba6c0ad748a8","repo":"infiniflow/ragflow","slug":"can-t-init-admin","errorCode":null,"errorMessage":"Can't init admin.","messagePattern":"Can't init admin\\.","errorType":"http","errorClass":"AdminException","httpStatus":500,"severity":"critical","filePath":"admin/server/auth.py","lineNumber":102,"sourceCode":"        else:\n            return None\n\n\ndef init_default_admin():\n    # Verify that at least one active admin user exists. If not, create a default one.\n    users = UserService.query(is_superuser=True)\n    if not users:\n        default_admin = {\n            \"id\": uuid.uuid1().hex,\n            \"password\": encode_to_base64(\"admin\"),\n            \"nickname\": \"admin\",\n            \"is_superuser\": True,\n            \"email\": \"admin@ragflow.io\",\n            \"creator\": \"system\",\n            \"status\": \"1\",\n        }\n        if not UserService.save(**default_admin):\n            raise AdminException(\"Can't init admin.\", 500)\n        add_tenant_for_admin(default_admin, UserTenantRole.OWNER)\n    elif not any([u.is_active == ActiveEnum.ACTIVE.value for u in users]):\n        raise AdminException(\"No active admin. Please update 'is_active' in db manually.\", 500)\n    else:\n        default_admin_rows = [u for u in users if u.email == \"admin@ragflow.io\"]\n        if default_admin_rows:\n            default_admin = default_admin_rows[0].to_dict()\n            exist, default_admin_tenant = TenantService.get_by_id(default_admin[\"id\"])\n            if not exist:\n                add_tenant_for_admin(default_admin, UserTenantRole.OWNER)\n\n\ndef add_tenant_for_admin(user_info: dict, role: str):\n\n    tenant = {\n        \"id\": user_info[\"id\"],\n        \"name\": user_info[\"nickname\"] + \"‘s Kingdom\",\n        \"llm_id\": settings.CHAT_MDL,","sourceCodeStart":84,"sourceCodeEnd":120,"githubUrl":"https://github.com/infiniflow/ragflow/blob/554fb1133ac3861732235ad9c377eb5e0a770665/admin/server/auth.py#L84-L120","documentation":"Raised during admin server bootstrap (admin/server/auth.py:102) when no superuser exists in the user table and UserService.save() of the hard-coded default admin (admin@ragflow.io / base64('admin')) returns falsy — i.e. the INSERT failed at the database layer. It aborts server startup because the system cannot guarantee an administrative account exists. The AdminException carries HTTP 500.","triggerScenarios":"First boot of the admin server (or a wipe of the user table) against a broken database: MySQL/Postgres unreachable mid-init, schema not migrated (table missing), a column constraint violation on the insert, or duplicate id/email causing the save to fail. UserService.save returning None/False on any DB error maps directly to this raise.","commonSituations":"Running the admin server before applying DB migrations or before docker-compose-base services (MySQL) are healthy; pointing SAUTH/DB env vars at a stale database that already has a conflicting admin@ragflow.io row; schema drift after upgrading RAGFlow without running the migration scripts.","solutions":["Check the metadata DB is reachable and migrations are applied (the user table exists and matches current models) before starting the admin server.","Inspect server logs immediately above this raise — Peewee logs the underlying DB error that made UserService.save fail.","If a conflicting/partial admin row exists, delete or repair it in the user table so the bootstrap insert can succeed on restart.","Restart the admin server after fixing the DB; bootstrap is idempotent (it only inserts when no superuser exists)."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"from api.db.services import UserService\nfrom common.constants import ActiveEnum\nusers = UserService.query(is_superuser=True)\nif not users:\n    # bootstrap insert will run; verify DB writability first\n    probe = UserService.save(id=\"probe\", email=\"probe@invalid\")  # only in a sandbox\n    assert probe, \"user table not writable; fix DB before starting admin server\"","typeGuard":null,"tryCatchPattern":"from api.common.exceptions import AdminException\ntry:\n    init_admin()  # auth bootstrap\nexcept AdminException as e:\n    if \"Can't init admin\" in str(e):\n        # inspect DB connectivity/migrations before restart\n        raise","preventionTips":["Run database migrations before every admin-server start.","Make startup depend on a DB healthcheck (docker compose depends_on with condition: service_healthy).","Monitor for the absence of any superuser row; alert before restart, not after."],"tags":["bootstrap","database","admin","startup"],"backgroundTag":null,"analyzedSha":"554fb1133ac3861732235ad9c377eb5e0a770665","analyzedAt":"2026-08-15T09:20:16.380Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}