{"record":{"id":"aa59ed3faacb5981","repo":"theonedev/onedev","slug":"unable-to-find-iteration-value","errorCode":null,"errorMessage":"Unable to find iteration: ${value}","messagePattern":"Unable to find iteration: (.+?)","errorType":"exception","errorClass":"NotFoundException","httpStatus":404,"severity":"error","filePath":"server-core/src/main/java/io/onedev/server/util/QueryUtils.java","lineNumber":190,"sourceCode":"\n\tpublic static Long getNumber(String value) {\n\t\tif (value.startsWith(\"#\"))\n\t\t\tvalue = value.substring(1);\n\t\ttry {\n\t\t\treturn Long.parseLong(value);\n\t\t} catch (NumberFormatException e) {\n\t\t\tthrow new NotAcceptableException(\"Invalid number: \" + value);\n\t\t}\n\t}\n\t\n\tpublic static Iteration getIteration(@Nullable Project project, String value) {\n\t\tif (project != null && !value.contains(\":\")) \n\t\t\tvalue = project.getPath() + \":\" + value;\n\t\tIteration iteration = OneDev.getInstance(IterationService.class).findInHierarchy(value);\n\t\tif (iteration != null)\n\t\t\treturn iteration;\n\t\telse\n\t\t\tthrow new NotFoundException(\"Unable to find iteration: \" + value);\n\t}\n\n\tpublic static <T> Path<T> getPath(Path<?> root, String pathName) {\n\t\tint index = pathName.indexOf('.');\n\t\tif (index != -1) {\n\t\t\tPath<T> path = root.get(pathName.substring(0, index));\n\t\t\tfor (String field: Splitter.on(\".\").split(pathName.substring(index+1))) \n\t\t\t\tpath = path.get(field);\n\t\t\treturn path;\n\t\t} else {\n\t\t\treturn root.get(pathName);\n\t\t}\n\t}\n\n\tpublic static boolean isInsideQuote(String value) {\n\t\treturn INSIDE_QUOTE.matcher(value.trim()).matches();\n\t}\n","sourceCodeStart":172,"sourceCodeEnd":208,"githubUrl":"https://github.com/theonedev/onedev/blob/d44925c47c37992c828ea673a5f9620539bc3ff2/server-core/src/main/java/io/onedev/server/util/QueryUtils.java#L172-L208","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify the iteration name exists in the project (or an ancestor project) in the OneDev UI","Add the project scope prefix (e.g. 'group/project:Sprint 5') or pass the correct default Project","Update saved queries after iteration renames or removals","Check the iteration is not defined in a sibling/child project — findInHierarchy only searches upward"],"exampleFix":"// before\nIteration it = QueryUtils.getIteration(project, \"Sprint 5\");\n// after\nIteration it = QueryUtils.getIteration(project, \"group/my-project:Sprint 6\");","handlingStrategy":"validation","validationCode":"Iteration it = OneDev.getInstance(IterationService.class).findInHierarchy(value);\nif (it == null) throw new UserException(\"Iteration '\" + value + \"' not found in project hierarchy\");","typeGuard":"boolean iterationExists(String scopedName) {\n    return OneDev.getInstance(IterationService.class).findInHierarchy(scopedName) != null;\n}","tryCatchPattern":"try {\n    Iteration it = QueryUtils.getIteration(project, value);\n} catch (NotFoundException e) {\n    logger.warn(\"Iteration not found: {}\", value);\n}","preventionTips":["Use the exact iteration name as shown in the UI, including case","Scope with the project prefix when iterations may exist in parent projects","Revisit saved queries each planning cycle in case iterations were renamed"],"tags":["iteration","lookup","not-found","onedev"],"backgroundTag":"entity-not-found","analyzedSha":"d44925c47c37992c828ea673a5f9620539bc3ff2","analyzedAt":"2026-09-06T07:18:27.995Z","contentChangedAt":"2026-09-06T07:18:27.995Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}