What causes "Unable to find version" in theonedev/onedev?

Add the missing 'version: N' key back at the top level of the YAML file with the correct version number

theonedev/onedev · error · ExplicitException

Unable to find version

Error message

Unable to find version

What it means

VersionedYamlDoc.getVersion scans the YAML mapping nodes for a top-level 'version' key, which records the doc format version used during migration. If no 'version' tuple exists, it throws ExplicitException('Unable to find version'), meaning the YAML cannot be safely deserialized to the current model.

Source

Thrown at server-core/src/main/java/io/onedev/server/data/migration/VersionedYamlDoc.java:86

			}
		}
		
        return (T) new OneYaml().construct(this);
	}
	
	public static VersionedYamlDoc fromBean(Object bean) {
		VersionedYamlDoc doc = new VersionedYamlDoc((MappingNode) new OneYaml().represent(bean));
		doc.setVersion(MigrationHelper.getVersion(HibernateProxyHelper.getClassWithoutInitializingProxy(bean)));
		return doc;
	}
	
	private String getVersion() {
		for (NodeTuple tuple: getValue()) {
			ScalarNode keyNode = (ScalarNode) tuple.getKeyNode();
			if (keyNode.getValue().equals("version")) 
				return ((ScalarNode)tuple.getValueNode()).getValue();
		}
		throw new ExplicitException("Unable to find version");
	}
	
	private void removeVersion() {
		for (Iterator<NodeTuple> it = getValue().iterator(); it.hasNext();) {
			ScalarNode keyNode = (ScalarNode) it.next().getKeyNode();
			if (keyNode.getValue().equals("version")) 
				it.remove();
		}
	}
	
	private void setVersion(String version) {
		ScalarNode versionNode = null;
		for (NodeTuple tuple:  getValue()) {
			ScalarNode keyNode = (ScalarNode) tuple.getKeyNode();
			if (keyNode.getValue().equals("version")) {
				((ScalarNode) tuple.getValueNode()).setValue(version);
				break;
			}

View on GitHub (pinned to d44925c47c)

Solutions

Add the missing 'version: N' key back at the top level of the YAML file with the correct version number
Re-export the data from the original OneDev version to regenerate a proper versioned YAML
Use the import feature of OneDev instead of hand-crafted YAML files
Check the file was not truncated — version is normally the first key

Example fix

# before
name: my-project
url: https://example.com
# after
version: 1
name: my-project
url: https://example.com

Defensive patterns

Strategy: validation

Validate before calling

// before deserializing YAML
doc.load(file);
if (!doc.keySet().contains("version")) rejectImport(file, "missing version key");

Try / catch

try { VersionedYamlDoc.fromFile(f).toBean(type); } catch (ExplicitException e) { if (e.getMessage().equals("Unable to find version")) { requireVersionedYaml(f); } }

Prevention

Always keep 'version' as the first key in versioned YAML files
Use OneDev's export feature rather than hand-writing YAML
Validate YAML against a versioned template before import
Diff hand-edited YAML against the original export

When it happens

Trigger: toBean calls getVersion on a YAML doc parsed from an import/backup file that lacks the mandatory 'version' key at the mapping root.

Common situations: Importing a YAML file hand-edited to drop the version field, files exported by older/incompatible tools, or YAML copied from documentation examples without the version entry.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

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