theonedev/onedev · error · ExplicitException

Unable to upgrade specified installation due to above error

Error message

Unable to upgrade specified installation due to above error

What it means

During upgrade, if reading the database data version itself failed, getDataVersion returns dbDataVersion == -1 (the error is logged just above in the console). The upgrade.call() method detects this sentinel and aborts with 'Unable to upgrade specified installation due to above error' rather than proceeding with unknown version state.

Source

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

						hibernateProps = Strings.CS.replace(hibernateProps, "sampledb", "internaldb");
						writeStringToFile(hibernatePropsFile, hibernateProps, UTF_8);
					}
				} 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

Read the error logged immediately above this message in the upgrade console output — it names the root cause of version detection failure.
Fix database connectivity/credentials so the upgrade can read the schema version.
Repair or restore the database schema if version tables are corrupted, then retry the upgrade.
Re-run the upgrade command once the underlying version-detection issue is resolved.

Defensive patterns

Strategy: retry

Validate before calling

// verify DB connectivity before upgrading
try (var conn = DriverManager.getConnection(dbUrl, user, pass)) {
    if (!conn.isValid(5)) throw new IllegalStateException("DB unreachable");
}

Try / catch

try {
    upgrade.call();
} catch (ExplicitException e) {
    if (e.getMessage().contains("due to above error"))
    logger.error("See preceding console error for the version-detection failure");
}

Prevention

Always read the error printed immediately before this message — it contains the real cause.
Check database availability and credentials before starting an upgrade.
Fix any corrupted schema/version tables before retrying.

When it happens

Trigger: Running the 'upgrade' command when getDataVersion could not determine the database version — e.g. the version query against the DB threw an exception, the DB is unreachable, or schema inspection failed — leaving dbDataVersion == -1.

Common situations: Database connection problems during upgrade; corrupted or partially migrated schema where version detection fails; running upgrade with wrong DB credentials or against a down database.

Related errors

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