theonedev/onedev · critical · ExplicitException

OneDev is unable to restore old database, please do it manua

Error message

OneDev is unable to restore old database, please do it manually by first resetting it (delete and create), and then running below command:

What it means

OneDev throws this ExplicitException during a failed self-upgrade when it could not automatically restore the old database from the backup taken before the upgrade. It tells the admin to manually reset the database (drop and recreate) and run the generated restore-db script to re-import the backup.

Source

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

										logger.info("Old database restored");
										dbChanged = false;
									} catch (Exception e) {
										logger.error("Error restoring old database", e);
									}
								}
								
								StringBuilder errorMessage = new StringBuilder(String.format("!! Failed to upgrade %s", upgradeDir.getAbsolutePath()));
								if (dbChanged) {
									if (inDocker)
										errorMessage.append("\nOneDev is unable to restore old database, please do it manually by first resetting it (delete and create), and then exec into the container to run below command:");
									else
										errorMessage.append("\nOneDev is unable to restore old database, please do it manually by first resetting it (delete and create), and then running below command:");										
									if (SystemUtils.IS_OS_WINDOWS) 
										errorMessage.append("\n" + upgradeDir.getAbsolutePath() + File.separator + "bin" + File.separator + "restore-db.bat " + dbBackupFile.getAbsolutePath());
									else 
										errorMessage.append("\n" + upgradeDir.getAbsolutePath() + File.separator + "bin" + File.separator + "restore-db.sh " + dbBackupFile.getAbsolutePath());
								}
								throw new ExplicitException(errorMessage.toString());
							} else {
								logger.info("Successfully upgraded {}", upgradeDir.getAbsolutePath());
								FileUtils.deleteDir(programBackup);
							}
							return null;
						}
					};
					
					var maintenanceFile = OneDev.getMaintenanceFile(upgradeDir);
					FileUtils.touchFile(maintenanceFile);
					MaintenanceProbeServer.start(upgradeDir);
					try {
						var hibernateConfig = new HibernateConfig(upgradeDir);
						if (!hibernateConfig.isHSQLDialect()) {
							var classLoader = newSiteLibClassLoader(upgradeDir);
							try (var conn = openConnection(hibernateConfig, classLoader)) {
								callWithLock(conn, () -> callable.call());
							}

View on GitHub (pinned to d44925c47c)

Solutions

Delete the current (half-upgraded) database and recreate an empty one with the same name/owner
Run the generated script: <upgradeDir>/bin/restore-db.bat (Windows) or restore-db.sh (Linux) with the db backup file path shown in the error
Restore the previous OneDev program files from the program backup directory if the upgrade also modified them
Check database connectivity/credentials before retrying the upgrade

Example fix

# manual restore after failed upgrade
dropdb onedev && createdb onedev
/path/to/onedev-upgrade/bin/restore-db.sh /path/to/site-1.0/db_backup.dump

Defensive patterns

Strategy: fallback

Validate before calling

// before upgrade: verify DB reachable and backup exists
if (!db reachable || !dbBackupFile.exists()) abortUpgrade();

Try / catch

try { upgrade(); } catch (ExplicitException e) { if (e.getMessage().contains("unable to restore old database")) { resetDatabase(); runScript(upgradeDir + "/bin/restore-db.sh", dbBackupFile); } }

Prevention

Always run upgrades against a tested, recent DB backup
Upgrade during a maintenance window with stable power/process supervision
Verify DB user has full DDL and data privileges
Keep the upgrade directory's restore scripts accessible

When it happens

Trigger: The 'call' method of the Upgrade command handler performs the upgrade, detects a failure during DB upgrade/restore, and the automatic restore path could not complete, so it appends this message and throws.

Common situations: Upgrade interrupted mid-way (power loss, killed process), DB plugin/driver mismatch, insufficient DB permissions for the OneDev user, or corrupted backup file leaving the DB in a half-upgraded state.

Related errors

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