theonedev/onedev · error · ExplicitException

OneDev program is too old, please use a newer version

Error message

OneDev program is too old, please use a newer version

What it means

Upgrade.call() compares the newest data version supported by the running program (newAppDataVersion from DataMigrator) with the old application data version found in the upgrade dir. If the program's version is older than the data version on disk (i.e. the installation's data has already been migrated by a newer OneDev), the upgrade aborts with 'OneDev program is too old, please use a newer version' to prevent downgrading the data format.

Source

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

					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);
									}
								}
							} catch (IOException e) {
								throw new RuntimeException(e);

View on GitHub (pinned to d44925c47c)

Solutions

  1. Download and run a OneDev version equal to or newer than the one that last upgraded the data.
  2. If downgrade is unavoidable, restore the site directory and database from a backup taken before the newer version ran.
  3. Check the data version in logs/upgrade output to identify which program version is required.
  4. Avoid mixing program versions and site data; keep container tags and data volumes in sync.
Defensive patterns

Strategy: validation

Validate before calling

// ensure the target program version is not older than the data
if (runningProgramVersion < lastVersionThatUpgradedData)
    throw new IllegalStateException("Use a OneDev version >= " + lastVersionThatUpgradedData);

Try / catch

try {
    upgrade.call();
} catch (ExplicitException e) {
    if (e.getMessage().contains("OneDev program is too old"))
    logger.error("Data already migrated by a newer version; deploy matching or newer build");
}

Prevention

When it happens

Trigger: Running 'upgrade' with an older OneDev distribution against a site directory whose data was already migrated by a newer version — newAppDataVersion < oldAppDataVersion.

Common situations: Downgrading OneDev after trying a newer release; deploying an older Docker image over an upgraded data volume; running an old version binary against a site directory that a newer version already upgraded.

Related errors

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