What causes "Incorrect data format: illegal data version" in theonedev/onedev?

Restore the db_version file from a known-good site backup

theonedev/onedev · error · RuntimeException

Incorrect data format: illegal data version

Error message

Incorrect data format: illegal data version

What it means

migrateData reads the site db_version XML file via VersionedXmlDoc and expects the root element to contain exactly one child. If the root has a different number of elements, the file's data format is illegal and it throws this RuntimeException.

Source

Thrown at server-core/src/main/java/io/onedev/server/data/DefaultDataService.java:337

				throw ExceptionUtils.unchecked(e);
		}
	}

	private File getVersionFile(File dataDir) {
		File versionFile = new File(dataDir, ModelVersion.class.getSimpleName() + "s.xml");
		if (!versionFile.exists())
			versionFile = new File(dataDir, "VersionTables.xml");
		return versionFile;
	}
	
	@Override
	public void migrateData(File dataDir) {
		File versionFile = getVersionFile(dataDir);
		
		VersionedXmlDoc dom = VersionedXmlDoc.fromFile(versionFile);
		List<Element> elements = dom.getRootElement().elements();
		if (elements.size() != 1)
			throw new RuntimeException("Incorrect data format: illegal data version");
		Element versionElement = elements.iterator().next().element(ModelVersion.PROP_VERSION_COLUMN);		
		if (versionElement == null) {
			throw new RuntimeException("Incorrect data format: no data version");
		}
		
		if (MigrationHelper.migrate(versionElement.getText(), new DataMigrator(), dataDir)) {
			// load version file again in case we changed something of it while migrating
			versionFile = getVersionFile(dataDir);
			dom = VersionedXmlDoc.fromFile(versionFile);
			elements = dom.getRootElement().elements();
			Preconditions.checkState(elements.size() == 1);
			versionElement = Preconditions.checkNotNull(elements.iterator().next().element(ModelVersion.PROP_VERSION_COLUMN));		
			versionElement.setText(MigrationHelper.getVersion(DataMigrator.class));
			dom.writeToFile(versionFile, false);
		}		
	}

	/**

View on GitHub (pinned to d44925c47c)

Solutions

Restore the db_version file from a known-good site backup
Recreate the file with the correct single-element structure containing the version column entry
If the site data is unusable, re-initialize the site data directory and re-import projects
Diff the file against one from a working installation of the same version

Example fix

<!-- before: corrupted multiple roots -->
<root><version>10</version><version>9</version></root>
<!-- after -->
<root><version>10</version></root>

Defensive patterns

Strategy: validation

Validate before calling

Document dom = parse(dbVersionFile);
if (dom.getRootElement().elements().size() != 1) restoreFromBackup(dbVersionFile);

Try / catch

try { migrateData(dir); } catch (RuntimeException e) { if (e.getMessage().contains("illegal data version")) { restoreDbVersionFile(); } }

Prevention

Never hand-edit the db_version file
Back up the whole site data directory before maintenance
Copy data directories atomically, not partially
Validate XML after any manual tooling touches it

When it happens

Trigger: The db_version file in the data directory was hand-edited, truncated, corrupted, or produced by an incompatible tool so its root element has zero or multiple children.

Common situations: Manual editing of the site data version file, disk corruption, partial file copy during site backup/restore, or merging data directories.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

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