theonedev/onedev · error · RuntimeException

Failed to apply database constraints. If this error is cause

Error message

Failed to apply database constraints. If this error is caused by foreign key constraint violations, you may fix it via your database sql tool, and then run apply-db-constraints to reapply database constraints

What it means

During a database restore, RestoreDatabase.doRestore calls dataService.applyConstraints(conn) to reapply foreign key and other constraints to the restored data. If that fails for any reason — typically because the restored dump contains rows violating foreign keys — it wraps the failure in a RuntimeException advising the user to fix violations with a SQL tool and re-run the apply-db-constraints command.

Source

Thrown at server-core/src/main/java/io/onedev/server/commandhandler/RestoreDatabase.java:133

			});
		} catch (SQLException e) {
			throw new RuntimeException(e);
		}
				
		logger.info("Importing data into database...");
		dataService.importData(dataDir);

		try (var conn = dataService.openConnection()) {
			callWithTransaction(conn, () -> {
				logger.info("Applying foreign key constraints...");
				try {
					dataService.applyConstraints(conn);
				} catch (Exception e) {
					var message = String.format("Failed to apply database constraints. If this error is caused by " +
							"foreign key constraint violations, you may fix it via your database sql tool, and " +
							"then run %s to reapply database constraints", 
							Command.getScript("apply-db-constraints"));
					throw new RuntimeException(message);
				}
				return null;
			});
		} catch (SQLException e) {
			throw new RuntimeException(e);
		}
	}

	@Override
	public void stop() {
		sessionFactoryService.stop();
	}
	
}

View on GitHub (pinned to d44925c47c)

Solutions

Follow the message: fix foreign key violations with a SQL tool (delete/update orphaned rows), then run the apply-db-constraints script to reapply constraints.
Identify violating rows by querying child rows whose foreign keys have no parent match.
Re-create the restore from a clean, consistent backup instead of patching a corrupt dump.
Ensure the source and target database engines/versions are compatible so constraint SQL applies cleanly.

Example fix

-- find orphaned rows before reapplying constraints
SELECT c.* FROM issue c LEFT JOIN project p ON c.project_id = p.id
WHERE p.id IS NULL;
DELETE FROM issue WHERE project_id NOT IN (SELECT id FROM project);
-- then in shell
./apply-db-constraints

Defensive patterns

Strategy: retry

Validate before calling

-- detect orphaned foreign keys before reapplying constraints
SELECT child.* FROM child_table child
LEFT JOIN parent_table p ON child.parent_id = p.id
WHERE p.id IS NULL;

Try / catch

try {
    restoreCommand.start();
} catch (RuntimeException e) {
    if (e.getMessage().startsWith("Failed to apply database constraints"))
    logger.error("Fix FK violations in DB, then run apply-db-constraints");
}

Prevention

Take backups from databases with constraints fully applied and data consistent.
Never hand-edit restored dumps without re-checking referential integrity.
Restore into the same (or compatible) database engine/version the dump came from.
After any constraint failure, run the apply-db-constraints script after cleaning orphan rows.

When it happens

Trigger: Running the 'restore' command where the imported data violates database constraints (orphaned foreign keys, missing referenced rows), causing DataService.applyConstraints to fail during doRestore.

Common situations: Restoring a backup produced from a database where constraints had been previously dropped/relaxed; hand-edited or partially imported dumps; migrating between database engines with different constraint semantics; interrupted restore leaving partial data.

Related errors

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