wg-easy/wg-easy · critical · Error

You are using an invalid Configuration for wg-easy Please f

Error message

You are using an invalid Configuration for wg-easy
Please follow the instructions on https://wg-easy.github.io/wg-easy/latest/advanced/migrate/from-14-to-15/ to migrate

What it means

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.

Source

Thrown at src/server/utils/WireGuard.ts:301

    for (const client of clients) {
      if (
        client.oneTimeLink !== null &&
        new Date() > new Date(client.oneTimeLink.expiresAt)
      ) {
        WG_DEBUG(`OneTimeLink for Client ${client.id} expired.`);
        await Database.oneTimeLinks.delete(client.id);
        // otl does not need wireguard sync
      }
    }

    if (needsSave) {
      await this.saveConfig();
    }
  }
}

if (OLD_ENV.PASSWORD || OLD_ENV.PASSWORD_HASH) {
  throw new Error(
    `
You are using an invalid Configuration for wg-easy
Please follow the instructions on https://wg-easy.github.io/wg-easy/latest/advanced/migrate/from-14-to-15/ to migrate
`
  );
}

// TODO: make static or object

export default new WireGuard();

View on GitHub (pinned to 5c38c1427a)

Solutions

1. Remove PASSWORD and PASSWORD_HASH from your environment (docker-compose.yml, .env, or docker run -e flags)
2. Restart the container; set up the admin account via the web UI as per v15 behavior
3. If you used PASSWORD_HASH, migrate credentials following https://wg-easy.github.io/wg-easy/latest/advanced/migrate/from-14-to-15/
4. Pin to the v14 image temporarily if you cannot migrate yet, and plan the migration

Example fix

// before (docker-compose.yml)
environment:
  - PASSWORD=hunter2
// after
environment: [] # set up the account in the web UI (wg-easy v15+)

// Run before launching wg-easy v15+
if (process.env.PASSWORD || process.env.PASSWORD_HASH) {
  throw new Error('Remove PASSWORD/PASSWORD_HASH — auth is managed in the UI since v15');
}

process.on('uncaughtException', (err) => {
  if (err.message.includes('invalid Configuration for wg-easy')) {
    console.error('Legacy v14 env vars detected; see the 14→15 migration guide');
    process.exit(78);
  }
  throw err;
});

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Missing environment variable: ${env}
• Invalid Config
• Hooks not found
• WireGuard exited with the error: Cannot find device "${wgInt
• Invalid firewall entry "${entry}": Protocol (/${proto}) requ

AI-assisted analysis of wg-easy/wg-easy@5c38c1427a (2026-08-30). Data as JSON: /api/errors/d706ebbe7ca8b96a. Report an issue: GitHub.