theonedev/onedev · error · ExplicitException

Iteration '${iterationName}' not found

Error message

Iteration '${iterationName}' not found

What it means

For each name in the "iterations" list, createIssue resolves an iteration via IterationService.findInHierarchy(project, iterationName); when no matching iteration exists it throws this ExplicitException naming the missing iteration.

Source

Thrown at server-core/src/main/java/io/onedev/server/ai/IssueHelper.java:303

            var subscriptionService = OneDev.getInstance(SubscriptionService.class);
            if (!subscriptionService.isSubscriptionActive())
                throw new ExplicitException("An active subscription is required for this feature");
            if (!project.isTimeTracking())
                throw new ExplicitException("Time tracking needs to be enabled for the project");
            if (!SecurityUtils.canScheduleIssues(subject, project))
                throw new UnauthorizedException("Issue schedule permission required to set own estimated time");
            issue.setOwnEstimatedTime(ownEstimatedTime * 60);
        }

        List<String> iterationNames = (List<String>) data.remove("iterations");
        if (iterationNames != null) {
            if (!SecurityUtils.canScheduleIssues(subject, project))
                throw new UnauthorizedException("Issue schedule permission required to set iterations");
            var iterationService = OneDev.getInstance(IterationService.class);
            for (var iterationName : iterationNames) {
                var iteration = iterationService.findInHierarchy(project, iterationName);
                if (iteration == null)
                    throw new ExplicitException("Iteration '" + iterationName + "' not found");
                IssueSchedule schedule = new IssueSchedule();
                schedule.setIssue(issue);
                schedule.setIteration(iteration);
                issue.getSchedules().add(schedule);
            }
        }

        issue.setProject(project);
        issue.setSubmitDate(new Date());
        issue.setSubmitter(SecurityUtils.getUser(subject));
        issue.setState(issueSetting.getInitialStateSpec().getName());

        issue.setFieldValues(FieldUtils.getFieldValues(subject, project, data));

        OneDev.getInstance(IssueService.class).open(issue);
        return issue;
    }

View on GitHub (pinned to d44925c47c)

Solutions

1. Check Project > Iterations for exact iteration names and correct the payload (names are matched within the project hierarchy)
2. Create the missing iteration before running the issue-creation call
3. List the project's iterations first (via API) and pick valid names

Example fix

// before
data.put("iterations", List.of("sprint 12")); // case mismatch
// after
data.put("iterations", List.of("Sprint 12")); // exact name from project iterations

// before createIssue, verify iteration names resolve
for (String name : (List<String>) data.getOrDefault("iterations", List.of()))
    if (OneDev.getInstance(IterationService.class).findInHierarchy(project, name) == null)
        throw new IllegalArgumentException("Unknown iteration: " + name);

try {
    issueHelper.createIssue(project, subject, data);
} catch (ExplicitException e) {
    if (e.getMessage().startsWith("Iteration '") && e.getMessage().endsWith("' not found")) {
        // refresh iteration list and correct the name
    }
}

When it happens

Trigger: The "iterations" list contains a name that does not match any iteration in the project or its parent hierarchy at creation time.

Common situations: Iteration renamed/closed before the automation ran; typo or case mismatch in the iteration name; iteration belongs to a different project branch of the hierarchy; AI tool hallucinating iteration names.

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

• Iteration '${iterationName}' not found
• No permission to schedule issue. Remove iterationIds if you
• Title is required
• Time tracking needs to be enabled for the project
• Issue schedule permission required to set iterations

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