theonedev/onedev · error · ExplicitException

Unable to upgrade specified installation as data version of

Error message

Unable to upgrade specified installation as data version of application and database is not the same

What it means

The upgrade command requires the database's data version to match either the old application data version (from the upgrade dir) or the new application data version being upgraded to. If dbDataVersion differs from both, the application and database are out of sync in an unsupported way and the upgrade aborts with this ExplicitException.

Source

Thrown at server-core/src/main/java/io/onedev/server/commandhandler/Upgrade.java:307

					}
				} catch (IOException e) {
					throw new RuntimeException(e);
				}
				
				try {
					var callable = new Callable<Void>() {
						@Override
						public Void call() {
							var newAppDataVersion = parseInt(MigrationHelper.getVersion(DataMigrator.class));
							var dataVersion = getDataVersion(upgradeDir);
							var oldAppDataVersion = dataVersion.app;
							var dbDataVersion = dataVersion.db;
							if (dbDataVersion == 0) 
								throw new ExplicitException("Unable to upgrade specified installation as database is not populated yet");
							if (dbDataVersion == -1) 
								throw new ExplicitException("Unable to upgrade specified installation due to above error");
							if (dbDataVersion != oldAppDataVersion && dbDataVersion != newAppDataVersion) 
								throw new ExplicitException("Unable to upgrade specified installation as data version of application and database is not the same");
							if (newAppDataVersion < oldAppDataVersion) 
								throw new ExplicitException("OneDev program is too old, please use a newer version");
							
							String timestamp = DateTimeFormat.forPattern(BACKUP_DATETIME_FORMAT).print(new DateTime());
							File programBackup = new File(upgradeDir, "site/program-backup/" + timestamp);
							FileUtils.createDir(programBackup);

							logger.info("Backing up old program files as {}...", programBackup.getAbsolutePath());
							try {
								for (File each : upgradeDir.listFiles()) {
									if (each.isFile()) {
										FileUtils.copyFileToDirectory(each, programBackup);
									} else if (!each.getName().equals("temp")
											&& !each.getName().equals("site")
											&& !each.getName().equals("internaldb")) {
										FileUtils.copyDirectoryToDirectory(each, programBackup);
									}
								}

View on GitHub (pinned to d44925c47c)

Solutions

Upgrade step by step through intermediate OneDev versions so the database migrates version by version to match.
Ensure the site directory and database belong to the same installation and version.
Check the recorded versions in upgrade logs to see exactly which versions are mismatched.
Restore a consistent backup matching the target version rather than mixing versions.

Defensive patterns

Strategy: validation

Validate before calling

// upgrade only one version step at a time
if (dbDataVersion != oldAppDataVersion && dbDataVersion != newAppDataVersion)
    throw new IllegalStateException("Upgrade through intermediate versions first");

Try / catch

try {
    upgrade.call();
} catch (ExplicitException e) {
    if (e.getMessage().contains("data version of application and database is not the same"))
    logger.error("App and DB versions diverge; upgrade step-by-step via intermediate versions");
}

Prevention

Upgrade through each intermediate version instead of jumping multiple releases.
Keep the site directory and database from the same installation together.
Record the current OneDev version and data version before any upgrade.
Never mix a restored database backup with a different version's site directory.

When it happens

Trigger: Running 'upgrade' when dbDataVersion != oldAppDataVersion && dbDataVersion != newAppDataVersion — e.g. skipping multiple intermediate versions, restoring a database of a different version into the site dir, or mixing site directories and databases from different installations.

Common situations: Upgrading across several OneDev versions in one hop; pairing a site/upgrade directory from one install with a database from another; restoring an old backup and then attempting a direct upgrade to the latest version.

Related errors

AI-assisted analysis of theonedev/onedev@d44925c47c (2026-09-06). Data as JSON: /api/errors/e52ea0289228e129. Report an issue: GitHub.