apache/maven · error · LifecyclePhaseNotFoundException

Unknown lifecycle phase "{}". You must specify a valid lifec

Error message

Unknown lifecycle phase "{}". You must specify a valid lifecycle phase or a goal in the format <plugin-prefix>:<goal> or <plugin-group-id>:<plugin-artifact-id>[:<plugin-version>]:<goal>. Available lifecycle phases are: {}.

What it means

DefaultLifecycleExecutionPlanCalculator.calculateLifecycleMappings() resolves each requested task to a lifecycle; if no known lifecycle contains the requested phase, it throws LifecyclePhaseNotFoundException with the full list of valid phase names. This is Maven's response to a task on the command line (or in a launched build) that is neither a valid phase nor a parseable plugin goal.

Source

Thrown at impl/maven-core/src/main/java/org/apache/maven/lifecycle/internal/DefaultLifecycleExecutionPlanCalculator.java:256

            } else {
                throw new IllegalStateException("unexpected task " + task);
            }
        }
        return mojoExecutions;
    }

    private Map<String, List<MojoExecution>> calculateLifecycleMappings(
            MavenSession session, MavenProject project, String lifecyclePhase)
            throws LifecyclePhaseNotFoundException, PluginNotFoundException, PluginResolutionException,
                    PluginDescriptorParsingException, MojoNotFoundException, InvalidPluginDescriptorException {
        /*
         * Determine the lifecycle that corresponds to the given phase.
         */

        Lifecycle lifecycle = defaultLifecycles.get(lifecyclePhase);

        if (lifecycle == null) {
            throw new LifecyclePhaseNotFoundException(
                    "Unknown lifecycle phase \"" + lifecyclePhase
                            + "\". You must specify a valid lifecycle phase"
                            + " or a goal in the format <plugin-prefix>:<goal> or"
                            + " <plugin-group-id>:<plugin-artifact-id>[:<plugin-version>]:<goal>. Available lifecycle phases are: "
                            + defaultLifecycles.getLifecyclePhaseList() + ".",
                    lifecyclePhase);
        }

        LifecycleMappingDelegate delegate;
        if (List.of(DefaultLifecycles.STANDARD_LIFECYCLES).contains(lifecycle.getId())) {
            delegate = standardDelegate;
        } else {
            delegate = delegates.getOrDefault(lifecycle.getId(), standardDelegate);
        }

        return delegate.calculateLifecycleMappings(session, project, lifecycle, lifecyclePhase);
    }

View on GitHub (pinned to e4093d4e12)

Solutions

1. Compare your phase against the 'Available lifecycle phases are:' list printed in the message — usually a typo
2. If you meant a plugin goal, use the full format <plugin-prefix>:<goal> or <groupId>:<artifactId>[:<version>]:<goal>
3. If the phase comes from a custom lifecycle, make sure the extension that defines it is loaded (build extension in the POM or ext= CLI arg)
4. Tab-complete or 'mvn help:describe' goals to verify names before scripting them

Example fix

# before
mvn complie

# after
mvn compile

// before running tasks, check each phase name against known lifecycles
Set<String> valid = defaultLifecycles.getLifeCycles().stream()
    .flatMap(l -> l.getPhases().stream()).collect(Collectors.toSet());
for (String task : tasks) {
    String phase = task.contains("@") ? task.substring(0, task.indexOf('@')) : task;
    if (!valid.contains(phase) && !phase.contains(":")) throw new IllegalArgumentException("Unknown phase: " + phase);
}

boolean isValidPhaseOrGoal(String task, Set<String> phases) {
    String phase = task.contains("@") ? task.substring(0, task.indexOf('@')) : task;
    return phases.contains(phase) || task.matches("[^\s:]+:[^\s:]+") || task.matches("[^\s:]+:[^\s:]+(:[^\s:]+)?:[^\s:]+");
}

catch (LifecyclePhaseNotFoundException e) {
    // e.getLifecyclePhase() is the offending name; compare with valid list and surface a typo hint
}

When it happens

Trigger: Running e.g. 'mvn complie' (typo), 'mvn intall -DskipTests', or a custom phase name only defined by an extension whose lifecycle is not registered; also programmatic task segments that contain a bare, unknown word that is not recognized as <prefix>:<goal>.

Common situations: Typos in phase names ('packge', 'depoy', 'verifi'); using a phase from a custom lifecycle (e.g. from the Paxdoc or Tycho lifecycles) without the corresponding extension enabled; scripts assuming a phase exists in a different Maven packaging.

Related errors

• Unknown lifecycle phase "{}". You must specify a valid lifec
• Illegal call to phase '{}'. The main phase '{}' will be used
• Unbounded range: {}
• Ranges overlap: {}
• Range defies version ordering: {}

AI-assisted analysis of apache/maven@e4093d4e12 (2026-08-21). Data as JSON: /api/errors/5d606136fc0954fe. Report an issue: GitHub.