theonedev/onedev · error · ExplicitException

Unable to upgrade specified installation as database is not

Error message

Unable to upgrade specified installation as database is not populated yet

What it means

The upgrade command reads the data version recorded in the database (dbDataVersion) from the upgrade directory and validates it before migrating. A value of 0 means the database was never populated with version metadata (setup never ran or the DB is empty), so the upgrade aborts with this ExplicitException.

Source

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

					String hibernateProps = FileUtils.readFileToString(hibernatePropsFile, UTF_8);
					if (hibernateProps.contains("sampledb")) {
						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")

View on GitHub (pinned to d44925c47c)

Solutions

Start the current OneDev version once and complete setup so the database is populated, then upgrade.
Verify the upgrade is targeting the correct site directory and database that contains existing data.
Check upgrade logs / getDataVersion output to confirm how the version was read from the upgrade dir.
If the DB is genuinely empty, skip the upgrade and just start the new version (it will initialize from scratch).

Defensive patterns

Strategy: validation

Validate before calling

// ensure DB is populated before upgrading
if (!databaseHasData(siteDir))
    throw new IllegalStateException("Database empty: start current version and complete setup before upgrading");

Try / catch

try {
    upgrade.call();
} catch (ExplicitException e) {
    if (e.getMessage().contains("database is not populated yet"))
    logger.error("Initialize the database with the current version before upgrading");
}

Prevention

Never run upgrade on a brand-new/empty site directory; start the app once first.
Verify the upgrade script points at the directory containing real data.
Confirm version metadata exists in the DB before automating upgrades.

When it happens

Trigger: Running the 'upgrade' command on an installation whose database has no recorded data version (getDataVersion returns dbDataVersion == 0) — typically an empty or never-initialized database.

Common situations: Upgrading a freshly created site directory before first launch/setup; pointing the upgrade at a wrong database that is empty; a broken installation where version metadata tables were never created.

Related errors

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