theonedev/onedev · error · NotFoundException

Unable to find iteration: ${value}

Error message

Unable to find iteration: ${value}

What it means

QueryUtils.getIteration resolves an iteration reference (optionally 'project:name') via IterationService.findInHierarchy, which searches the project and its parents. If no matching iteration is found, a NotFoundException 'Unable to find iteration' is thrown.

Source

Thrown at server-core/src/main/java/io/onedev/server/util/QueryUtils.java:190

	public static Long getNumber(String value) {
		if (value.startsWith("#"))
			value = value.substring(1);
		try {
			return Long.parseLong(value);
		} catch (NumberFormatException e) {
			throw new NotAcceptableException("Invalid number: " + value);
		}
	}
	
	public static Iteration getIteration(@Nullable Project project, String value) {
		if (project != null && !value.contains(":")) 
			value = project.getPath() + ":" + value;
		Iteration iteration = OneDev.getInstance(IterationService.class).findInHierarchy(value);
		if (iteration != null)
			return iteration;
		else
			throw new NotFoundException("Unable to find iteration: " + value);
	}

	public static <T> Path<T> getPath(Path<?> root, String pathName) {
		int index = pathName.indexOf('.');
		if (index != -1) {
			Path<T> path = root.get(pathName.substring(0, index));
			for (String field: Splitter.on(".").split(pathName.substring(index+1))) 
				path = path.get(field);
			return path;
		} else {
			return root.get(pathName);
		}
	}

	public static boolean isInsideQuote(String value) {
		return INSIDE_QUOTE.matcher(value.trim()).matches();
	}

View on GitHub (pinned to d44925c47c)

Solutions

1. Verify the iteration name exists in the project (or an ancestor project) in the OneDev UI
2. Add the project scope prefix (e.g. 'group/project:Sprint 5') or pass the correct default Project
3. Update saved queries after iteration renames or removals
4. Check the iteration is not defined in a sibling/child project — findInHierarchy only searches upward

Example fix

// before
Iteration it = QueryUtils.getIteration(project, "Sprint 5");
// after
Iteration it = QueryUtils.getIteration(project, "group/my-project:Sprint 6");

Iteration it = OneDev.getInstance(IterationService.class).findInHierarchy(value);
if (it == null) throw new UserException("Iteration '" + value + "' not found in project hierarchy");

boolean iterationExists(String scopedName) {
    return OneDev.getInstance(IterationService.class).findInHierarchy(scopedName) != null;
}

try {
    Iteration it = QueryUtils.getIteration(project, value);
} catch (NotFoundException e) {
    logger.warn("Iteration not found: {}", value);
}

When it happens

Trigger: Calling QueryUtils.getIteration with an iteration name that does not exist in the project or its parent projects; missing project prefix when project is null; iteration renamed or closed/removed before the query ran.

Common situations: Saved queries referencing sprints/iterations that were renamed at the end of a cycle; typos in iteration names; iterations belonging to a sibling project rather than an ancestor; case mismatches in the iteration name.

Understand the failure class

Background: "Not found" and "does not exist" errors: why "Task not found", "No such folder", and "Can't find" fire when a lookup comes back empty — this error's family across 14 libraries.

Related errors

• Unable to find project '${projectPath}'
• Unable to find issue: ${value}
• Unable to find pull request: ${value}
• Unable to find build: ${value}
• User not found: ${userName}

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