What causes "Iteration '${iterationName}' not found" in theonedev/onedev?

List the project's iterations first and use exact existing names.

theonedev/onedev · error · NotFoundException

Iteration '${iterationName}' not found

Error message

Iteration '${iterationName}' not found

What it means

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).

Source

Thrown at server-core/src/main/java/io/onedev/server/ai/TodResource.java:641

            if (!subscriptionService.isSubscriptionActive())
                throw new NotAcceptableException("An active subscription is required for this feature");
            if (!issue.getProject().isTimeTracking())
                throw new NotAcceptableException("Time tracking needs to be enabled for the project");
            if (!SecurityUtils.canScheduleIssues(subject, issue.getProject()))
                throw new UnauthorizedException("Issue schedule permission required to set own estimated time");
            issueChangeService.changeOwnEstimatedTime(user, issue, ownEstimatedTime*60);
        }

        @SuppressWarnings("unchecked")
        List<String> iterationNames = (List<String>) data.remove("iterations");
        if (iterationNames != null) {
            if (!SecurityUtils.canScheduleIssues(subject, issue.getProject()))
                throw new UnauthorizedException("Issue schedule permission required to set iterations");
            var iterations = new ArrayList<Iteration>();
            for (var iterationName : iterationNames) {
                var iteration = iterationService.findInHierarchy(issue.getProject(), iterationName);
                if (iteration == null)
                    throw new NotFoundException("Iteration '" + iterationName + "' not found");
                iterations.add(iteration);
            }
            issueChangeService.changeIterations(user, issue, iterations);
        }

        if (!data.isEmpty()) {
            if (!SecurityUtils.canEditIssueFields(subject, issue)) 
                throw new UnauthorizedException("No permission to update issue fields");

            issueChangeService.changeFields(user, issue, FieldUtils.getFieldValues(subject, issue.getProject(), data));
        }

        return IssueHelper.getDetail(currentProject, issue);
    }

    @Path("/change-issue-state")
    @POST
    public Map<String, Object> changeIssueState(

View on GitHub (pinned to d44925c47c)

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.

Example fix

// before
iterations: ["Sprint 1"] // iteration does not exist
// after: verify the name against the project's iteration list first
iterations: ["Backlog"]

Defensive patterns

Strategy: validation

Validate before calling

// resolve iteration names against the project's iteration list first
const validNames = new Set(iterations.map(i => i.name));
const bad = requested.filter(n => !validNames.has(n));
if (bad.length) throw new Error(`Unknown iterations: ${bad.join(", ")}`);

Type guard

function iterationExists(project, name) {
  return project.iterationsHierarchy.some(i => i.name === name);
}

Try / catch

try {
  await editIssue(project, ref, { iterations: names });
} catch (e) {
  if (e.status === 404 || /Iteration '.*' not found/.test(e.message)) {
    // refresh the iteration list and retry with corrected names
  } else throw e;
}

Prevention

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.

When it happens

Trigger: 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).

Common situations: 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.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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