{"record":{"id":"d706ebbe7ca8b96a","repo":"wg-easy/wg-easy","slug":"you-are-using-an-invalid-configuration-for-wg-eas","errorCode":null,"errorMessage":"\nYou are using an invalid Configuration for wg-easy\nPlease follow the instructions on https://wg-easy.github.io/wg-easy/latest/advanced/migrate/from-14-to-15/ to migrate\n","messagePattern":"\nYou are using an invalid Configuration for wg-easy\nPlease follow the instructions on https://wg-easy\\.github\\.io/wg-easy/latest/advanced/migrate/from-14-to-15/ to migrate\n","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"src/server/utils/WireGuard.ts","lineNumber":301,"sourceCode":"    for (const client of clients) {\n      if (\n        client.oneTimeLink !== null &&\n        new Date() > new Date(client.oneTimeLink.expiresAt)\n      ) {\n        WG_DEBUG(`OneTimeLink for Client ${client.id} expired.`);\n        await Database.oneTimeLinks.delete(client.id);\n        // otl does not need wireguard sync\n      }\n    }\n\n    if (needsSave) {\n      await this.saveConfig();\n    }\n  }\n}\n\nif (OLD_ENV.PASSWORD || OLD_ENV.PASSWORD_HASH) {\n  throw new Error(\n    `\nYou are using an invalid Configuration for wg-easy\nPlease follow the instructions on https://wg-easy.github.io/wg-easy/latest/advanced/migrate/from-14-to-15/ to migrate\n`\n  );\n}\n\n// TODO: make static or object\n\nexport default new WireGuard();\n","sourceCodeStart":283,"sourceCodeEnd":312,"githubUrl":"https://github.com/wg-easy/wg-easy/blob/5c38c1427a0c6c62f1bbc6724233a71d931ac431/src/server/utils/WireGuard.ts#L283-L312","documentation":"This module-level guard throws at import/startup time when legacy environment variables PASSWORD or PASSWORD_HASH (from wg-easy v14 or earlier) are still set. Version 15 moved authentication into the UI/database, so these variables are no longer valid. The message points to the official migration guide from 14 to 15.","triggerScenarios":"Starting wg-easy v15+ with PASSWORD or PASSWORD_HASH defined in docker-compose env, .env file, or `docker run -e` — commonly because the deployment was upgraded in place without removing the old variables.","commonSituations":"Upgrading a docker-compose stack from wg-easy v14 to v15 while keeping old environment entries; copy-pasting an old v14 docker-compose.yml; CI/health-check scripts injecting PASSWORD for login automation.","solutions":["Remove PASSWORD and PASSWORD_HASH from your environment (docker-compose.yml, .env, or docker run -e flags)","Restart the container; set up the admin account via the web UI as per v15 behavior","If you used PASSWORD_HASH, migrate credentials following https://wg-easy.github.io/wg-easy/latest/advanced/migrate/from-14-to-15/","Pin to the v14 image temporarily if you cannot migrate yet, and plan the migration"],"exampleFix":"// before (docker-compose.yml)\nenvironment:\n  - PASSWORD=hunter2\n// after\nenvironment: [] # set up the account in the web UI (wg-easy v15+)","handlingStrategy":"validation","validationCode":"// Run before launching wg-easy v15+\nif (process.env.PASSWORD || process.env.PASSWORD_HASH) {\n  throw new Error('Remove PASSWORD/PASSWORD_HASH — auth is managed in the UI since v15');\n}","typeGuard":null,"tryCatchPattern":"process.on('uncaughtException', (err) => {\n  if (err.message.includes('invalid Configuration for wg-easy')) {\n    console.error('Legacy v14 env vars detected; see the 14→15 migration guide');\n    process.exit(78);\n  }\n  throw err;\n});","preventionTips":["Audit docker-compose.yml/.env when upgrading major versions","Remove PASSWORD and PASSWORD_HASH before upgrading from v14 to v15","Pin image versions explicitly and read the migration notes in release changelogs"],"tags":["configuration","environment","migration","startup"],"backgroundTag":"deprecated-env-config","analyzedSha":"5c38c1427a0c6c62f1bbc6724233a71d931ac431","analyzedAt":"2026-08-30T04:35:56.098Z","schemaVersion":2},"datasetVersion":"2026-08-30T08:17:16.595Z"}