{"record":{"id":"494f17c38031acb3","repo":"theonedev/onedev","slug":"iteration-iterationname-not-found-494f17","errorCode":null,"errorMessage":"Iteration '${iterationName}' not found","messagePattern":"Iteration '(.+?)' not found","errorType":"http","errorClass":"NotFoundException","httpStatus":404,"severity":"error","filePath":"server-core/src/main/java/io/onedev/server/ai/TodResource.java","lineNumber":641,"sourceCode":"            if (!subscriptionService.isSubscriptionActive())\n                throw new NotAcceptableException(\"An active subscription is required for this feature\");\n            if (!issue.getProject().isTimeTracking())\n                throw new NotAcceptableException(\"Time tracking needs to be enabled for the project\");\n            if (!SecurityUtils.canScheduleIssues(subject, issue.getProject()))\n                throw new UnauthorizedException(\"Issue schedule permission required to set own estimated time\");\n            issueChangeService.changeOwnEstimatedTime(user, issue, ownEstimatedTime*60);\n        }\n\n        @SuppressWarnings(\"unchecked\")\n        List<String> iterationNames = (List<String>) data.remove(\"iterations\");\n        if (iterationNames != null) {\n            if (!SecurityUtils.canScheduleIssues(subject, issue.getProject()))\n                throw new UnauthorizedException(\"Issue schedule permission required to set iterations\");\n            var iterations = new ArrayList<Iteration>();\n            for (var iterationName : iterationNames) {\n                var iteration = iterationService.findInHierarchy(issue.getProject(), iterationName);\n                if (iteration == null)\n                    throw new NotFoundException(\"Iteration '\" + iterationName + \"' not found\");\n                iterations.add(iteration);\n            }\n            issueChangeService.changeIterations(user, issue, iterations);\n        }\n\n        if (!data.isEmpty()) {\n            if (!SecurityUtils.canEditIssueFields(subject, issue)) \n                throw new UnauthorizedException(\"No permission to update issue fields\");\n\n            issueChangeService.changeFields(user, issue, FieldUtils.getFieldValues(subject, issue.getProject(), data));\n        }\n\n        return IssueHelper.getDetail(currentProject, issue);\n    }\n\n    @Path(\"/change-issue-state\")\n    @POST\n    public Map<String, Object> changeIssueState(","sourceCodeStart":623,"sourceCodeEnd":659,"githubUrl":"https://github.com/theonedev/onedev/blob/d44925c47c37992c828ea673a5f9620539bc3ff2/server-core/src/main/java/io/onedev/server/ai/TodResource.java#L623-L659","documentation":"Thrown as NotFoundException by editIssue when an iteration name supplied in the 'iterations' list cannot be resolved via iterationService.findInHierarchy in the issue's project. Iterations must exist in the project's hierarchy (project or inherited parent iterations).","triggerScenarios":"Passing an 'iterations' list to the AI tod editIssue endpoint containing a name that does not match any iteration in the project hierarchy (typo, deleted iteration, iteration living in a different project).","commonSituations":"Iteration renamed or deleted after the agent plan was generated; agent guesses iteration names instead of listing them; cross-project reference where the iteration belongs to another project's hierarchy.","solutions":["List the project's iterations first and use exact existing names.","Fix the iteration name spelling/case to match an existing iteration.","Create the missing iteration in the project before referencing it."],"exampleFix":"// before\niterations: [\"Sprint 1\"] // iteration does not exist\n// after: verify the name against the project's iteration list first\niterations: [\"Backlog\"]","handlingStrategy":"validation","validationCode":"// resolve iteration names against the project's iteration list first\nconst validNames = new Set(iterations.map(i => i.name));\nconst bad = requested.filter(n => !validNames.has(n));\nif (bad.length) throw new Error(`Unknown iterations: ${bad.join(\", \")}`);","typeGuard":"function iterationExists(project, name) {\n  return project.iterationsHierarchy.some(i => i.name === name);\n}","tryCatchPattern":"try {\n  await editIssue(project, ref, { iterations: names });\n} catch (e) {\n  if (e.status === 404 || /Iteration '.*' not found/.test(e.message)) {\n    // refresh the iteration list and retry with corrected names\n  } else throw e;\n}","preventionTips":["Always fetch the project's current iteration list before referencing names.","Handle renames/deletions of iterations in automated workflows.","Use iteration IDs when the API surface allows it."],"tags":["not-found","iterations","issues","onedev"],"backgroundTag":"resource-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"}