CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/maven-org-apache-maven--maven-core

Maven Core classes - the core engine of Apache Maven build system

—

Pending
Overview
Eval results
Files

exception-handling.mddocs/

Exception Handling

Maven Core provides a comprehensive exception hierarchy for handling errors across all build operations. Understanding these exceptions enables proper error handling and recovery strategies in Maven-based applications and plugins.

Core Maven Exceptions

MavenExecutionException

Base exception for Maven execution failures.

public class MavenExecutionException extends Exception {
    /**
     * Create exception with message and cause.
     *
     * @param message error message
     * @param cause underlying cause
     */
    public MavenExecutionException(String message, Throwable cause);
    
    /**
     * Create exception with message only.
     *
     * @param message error message
     */
    public MavenExecutionException(String message);
    
    /**
     * Create exception with cause only.
     *
     * @param cause underlying cause
     */
    public MavenExecutionException(Throwable cause);
}

BuildFailureException

Exception indicating build failure with project context.

public class BuildFailureException extends Exception {
    /**
     * Create build failure exception.
     *
     * @param message failure message
     * @param cause underlying cause
     */
    public BuildFailureException(String message, Throwable cause);
    
    /**
     * Create build failure exception with message.
     *
     * @param message failure message
     */
    public BuildFailureException(String message);
    
    /**
     * Get the project where build failed (if available).
     *
     * @return Maven project or null
     */
    public MavenProject getProject();
    
    /**
     * Get build phase where failure occurred.
     *
     * @return lifecycle phase
     */
    public String getPhase();
}

InternalErrorException

Exception for Maven internal errors and unexpected conditions.

public class InternalErrorException extends Exception {
    /**
     * Create internal error exception.
     *
     * @param message error message
     * @param cause underlying cause
     */
    public InternalErrorException(String message, Throwable cause);
    
    /**
     * Create internal error exception with message.
     *
     * @param message error message
     */
    public InternalErrorException(String message);
}

Core Exception Handling Example:

import org.apache.maven.MavenExecutionException;
import org.apache.maven.BuildFailureException;
import org.apache.maven.InternalErrorException;

public void handleMavenExecution(Maven maven, MavenExecutionRequest request) {
    try {
        MavenExecutionResult result = maven.execute(request);
        
        if (result.hasExceptions()) {
            handleExecutionExceptions(result.getExceptions());
        } else {
            System.out.println("Build completed successfully");
        }
        
    } catch (MavenExecutionException e) {
        System.err.println("Maven execution failed: " + e.getMessage());
        handleMavenExecutionException(e);
    } catch (InternalErrorException e) {
        System.err.println("Maven internal error: " + e.getMessage());
        e.printStackTrace();
        // Log for debugging, may indicate Maven bug
    }
}

private void handleExecutionExceptions(List<Throwable> exceptions) {
    for (Throwable exception : exceptions) {
        if (exception instanceof BuildFailureException) {
            BuildFailureException buildFailure = (BuildFailureException) exception;
            System.err.println("Build failed in project: " + 
                (buildFailure.getProject() != null ? buildFailure.getProject().getName() : "unknown"));
            System.err.println("Phase: " + buildFailure.getPhase());
        } else {
            System.err.println("Build exception: " + exception.getMessage());
        }
        
        if (exception.getCause() != null) {
            System.err.println("Caused by: " + exception.getCause().getMessage());
        }
    }
}

Project Exceptions

ProjectBuildingException

Exception thrown when project building fails.

public class ProjectBuildingException extends Exception {
    /**
     * Create project building exception.
     *
     * @param projectId project identifier
     * @param message error message
     * @param pomFile POM file that failed to build
     */
    public ProjectBuildingException(String projectId, String message, File pomFile);
    
    /**
     * Create project building exception with cause.
     *
     * @param projectId project identifier
     * @param message error message
     * @param pomFile POM file that failed to build
     * @param cause underlying cause
     */
    public ProjectBuildingException(String projectId, String message, File pomFile, Throwable cause);
    
    /**
     * Create exception for multiple project building results.
     *
     * @param projectId project identifier
     * @param message error message
     * @param results list of project building results with problems
     */
    public ProjectBuildingException(String projectId, String message, List<ProjectBuildingResult> results);
    
    /**
     * Get project identifier.
     *
     * @return project ID
     */
    public String getProjectId();
    
    /**
     * Get POM file that caused the failure.
     *
     * @return POM file
     */
    public File getPomFile();
    
    /**
     * Get project building results (for batch operations).
     *
     * @return list of building results
     */
    public List<ProjectBuildingResult> getResults();
}

ProjectCycleException

Exception thrown when circular dependencies are detected between projects.

import org.codehaus.plexus.util.dag.CycleDetectedException;

public class ProjectCycleException extends BuildFailureException {
    /**
     * Create project cycle exception.
     *
     * @param message error message describing the cycle
     */
    public ProjectCycleException(String message);
    
    /**
     * Create project cycle exception with cause.
     *
     * @param message error message describing the cycle
     * @param cause underlying cycle detection exception
     */
    public ProjectCycleException(String message, CycleDetectedException cause);
}

DependencyResolutionException

Exception for dependency resolution failures.

public class DependencyResolutionException extends Exception {
    /**
     * Create dependency resolution exception.
     *
     * @param result dependency resolution result with problems
     * @param message error message
     * @param cause underlying cause
     */
    public DependencyResolutionException(DependencyResolutionResult result, String message, Throwable cause);
    
    /**
     * Get dependency resolution result.
     *
     * @return resolution result containing resolved and unresolved dependencies
     */
    public DependencyResolutionResult getResult();
}

Project Exception Handling Example:

import org.apache.maven.project.ProjectBuildingException;
import org.apache.maven.project.DependencyResolutionException;
import org.apache.maven.project.ProjectBuildingResult;

public MavenProject handleProjectBuilding(ProjectBuilder projectBuilder, 
                                        File pomFile, 
                                        ProjectBuildingRequest request) {
    try {
        ProjectBuildingResult result = projectBuilder.build(pomFile, request);
        
        // Check for non-fatal problems
        if (!result.getProblems().isEmpty()) {
            System.out.println("Project built with " + result.getProblems().size() + " problems:");
            for (ModelProblem problem : result.getProblems()) {
                System.out.println("  " + problem.getSeverity() + ": " + problem.getMessage() +
                    " (line " + problem.getLineNumber() + ")");
            }
        }
        
        return result.getProject();
        
    } catch (ProjectBuildingException e) {
        System.err.println("Failed to build project: " + e.getProjectId());
        System.err.println("POM file: " + e.getPomFile());
        
        // Handle batch building results
        if (e.getResults() != null) {
            for (ProjectBuildingResult result : e.getResults()) {
                System.err.println("Project " + result.getProjectId() + ":");
                for (ModelProblem problem : result.getProblems()) {
                    System.err.println("  " + problem.getSeverity() + ": " + problem.getMessage());
                }
            }
        }
        
        throw new RuntimeException("Project building failed", e);
    }
}

public void handleDependencyResolution(ProjectDependenciesResolver resolver,
                                     MavenProject project, 
                                     MavenSession session) {
    try {
        DependencyResolutionResult result = resolver.resolve(project, 
            Arrays.asList(Artifact.SCOPE_COMPILE, Artifact.SCOPE_RUNTIME), session);
        
        System.out.println("Resolved " + result.getDependencies().size() + " dependencies");
        
    } catch (DependencyResolutionException e) {
        System.err.println("Dependency resolution failed for project: " + project.getName());
        
        DependencyResolutionResult result = e.getResult();
        if (result != null) {
            System.err.println("Resolved: " + result.getDependencies().size());
            System.err.println("Unresolved: " + result.getUnresolvedDependencies().size());
            
            // Log unresolved dependencies
            for (Dependency unresolved : result.getUnresolvedDependencies()) {
                System.err.println("  Unresolved: " + unresolved.getGroupId() + 
                    ":" + unresolved.getArtifactId() + ":" + unresolved.getVersion());
            }
            
            // Log collection errors
            for (Exception error : result.getCollectionErrors()) {
                System.err.println("  Collection error: " + error.getMessage());
            }
        }
    }
}

Plugin Exceptions

PluginManagerException

Base exception for plugin management operations.

public class PluginManagerException extends Exception {
    /**
     * Create plugin manager exception.
     *
     * @param plugin plugin that caused the error
     * @param message error message
     * @param cause underlying cause
     */
    public PluginManagerException(Plugin plugin, String message, Throwable cause);
    
    /**
     * Create plugin manager exception with message.
     *
     * @param plugin plugin that caused the error
     * @param message error message
     */
    public PluginManagerException(Plugin plugin, String message);
    
    /**
     * Get plugin that caused the exception.
     *
     * @return plugin instance
     */
    public Plugin getPlugin();
}

PluginNotFoundException

Exception thrown when a required plugin cannot be found.

public class PluginNotFoundException extends Exception {
    /**
     * Create plugin not found exception.
     *
     * @param plugin plugin that was not found
     */
    public PluginNotFoundException(Plugin plugin);
    
    /**
     * Create plugin not found exception with message.
     *
     * @param plugin plugin that was not found
     * @param message error message
     */
    public PluginNotFoundException(Plugin plugin, String message);
    
    /**
     * Get plugin that was not found.
     *
     * @return plugin instance
     */
    public Plugin getPlugin();
}

PluginResolutionException

Exception for plugin resolution failures.

public class PluginResolutionException extends Exception {
    /**
     * Create plugin resolution exception.
     *
     * @param plugin plugin that failed to resolve
     * @param cause underlying cause
     */
    public PluginResolutionException(Plugin plugin, Throwable cause);
    
    /**
     * Create plugin resolution exception with message.
     *
     * @param plugin plugin that failed to resolve
     * @param message error message
     * @param cause underlying cause
     */
    public PluginResolutionException(Plugin plugin, String message, Throwable cause);
    
    /**
     * Get plugin that failed to resolve.
     *
     * @return plugin instance
     */
    public Plugin getPlugin();
}

PluginExecutionException

Exception for plugin execution failures.

public class PluginExecutionException extends PluginManagerException {
    /**
     * Create plugin execution exception.
     *
     * @param project project being built
     * @param mojoExecution mojo execution that failed
     * @param message error message
     * @param cause underlying cause
     */
    public PluginExecutionException(MavenProject project, MojoExecution mojoExecution, 
                                   String message, Throwable cause);
    
    /**
     * Get project where execution failed.
     *
     * @return Maven project
     */
    public MavenProject getProject();
    
    /**
     * Get mojo execution that failed.
     *
     * @return mojo execution
     */
    public MojoExecution getMojoExecution();
}

Plugin Exception Handling Example:

import org.apache.maven.plugin.PluginNotFoundException;
import org.apache.maven.plugin.PluginResolutionException;
import org.apache.maven.plugin.PluginExecutionException;
import org.apache.maven.plugin.PluginManagerException;

public void handlePluginOperations(BuildPluginManager pluginManager, 
                                 MavenSession session,
                                 Plugin plugin) {
    try {
        // Load plugin
        PluginDescriptor descriptor = pluginManager.loadPlugin(plugin, 
            session.getCurrentProject().getPluginArtifactRepositories(),
            session.getRepositorySession());
        
        // Execute plugin goals
        for (MojoDescriptor mojo : descriptor.getMojos()) {
            MojoExecution execution = new MojoExecution(mojo);
            
            try {
                pluginManager.executeMojo(session, execution);
                System.out.println("Executed: " + plugin.getArtifactId() + ":" + mojo.getGoal());
                
            } catch (PluginExecutionException e) {
                System.err.println("Plugin execution failed:");
                System.err.println("  Plugin: " + e.getPlugin().getArtifactId());
                System.err.println("  Goal: " + e.getMojoExecution().getGoal());
                System.err.println("  Project: " + e.getProject().getName());
                System.err.println("  Error: " + e.getMessage());
                
                // Check for specific failure types
                if (e.getCause() instanceof MojoFailureException) {
                    System.err.println("  Mojo reported failure: " + e.getCause().getMessage());
                } else if (e.getCause() instanceof MojoExecutionException) {
                    System.err.println("  Mojo execution error: " + e.getCause().getMessage());
                }
            }
        }
        
    } catch (PluginNotFoundException e) {
        System.err.println("Plugin not found: " + e.getPlugin().getGroupId() + 
            ":" + e.getPlugin().getArtifactId() + ":" + e.getPlugin().getVersion());
        System.err.println("Check plugin repositories and coordinates");
        
    } catch (PluginResolutionException e) {
        System.err.println("Plugin resolution failed: " + e.getPlugin().getArtifactId());
        System.err.println("Error: " + e.getMessage());
        
        // May be caused by dependency conflicts or network issues
        if (e.getCause() instanceof ArtifactResolutionException) {
            System.err.println("Artifact resolution problem - check repositories");
        }
        
    } catch (PluginManagerException e) {
        System.err.println("Plugin management error: " + e.getMessage());
        if (e.getPlugin() != null) {
            System.err.println("Plugin: " + e.getPlugin().getArtifactId());
        }
    }
}

Lifecycle Exceptions

LifecycleExecutionException

Exception for lifecycle execution failures.

public class LifecycleExecutionException extends Exception {
    /**
     * Create lifecycle execution exception.
     *
     * @param message error message
     * @param cause underlying cause
     */
    public LifecycleExecutionException(String message, Throwable cause);
    
    /**
     * Create lifecycle execution exception with message.
     *
     * @param message error message
     */
    public LifecycleExecutionException(String message);
    
    /**
     * Create lifecycle execution exception with project context.
     *
     * @param project project where execution failed
     * @param message error message
     * @param cause underlying cause
     */
    public LifecycleExecutionException(MavenProject project, String message, Throwable cause);
    
    /**
     * Get project where lifecycle execution failed.
     *
     * @return Maven project or null
     */
    public MavenProject getProject();
}

LifecycleNotFoundException

Exception when a requested lifecycle is not found.

public class LifecycleNotFoundException extends Exception {
    /**
     * Create lifecycle not found exception.
     *
     * @param lifecycleId lifecycle identifier that was not found
     */
    public LifecycleNotFoundException(String lifecycleId);
    
    /**
     * Create lifecycle not found exception with message.
     *
     * @param lifecycleId lifecycle identifier
     * @param message error message
     */
    public LifecycleNotFoundException(String lifecycleId, String message);
    
    /**
     * Get lifecycle identifier that was not found.
     *
     * @return lifecycle ID
     */
    public String getLifecycleId();
}

Lifecycle Exception Handling Example:

import org.apache.maven.lifecycle.LifecycleExecutionException;
import org.apache.maven.lifecycle.LifecycleNotFoundException;

public void handleLifecycleExecution(LifecycleExecutor lifecycleExecutor, 
                                   MavenSession session,
                                   String... goals) {
    try {
        // Calculate execution plan
        MavenExecutionPlan plan = lifecycleExecutor.calculateExecutionPlan(session, goals);
        
        // Execute lifecycle
        lifecycleExecutor.execute(session);
        
        System.out.println("Lifecycle execution completed successfully");
        
    } catch (LifecycleExecutionException e) {
        System.err.println("Lifecycle execution failed: " + e.getMessage());
        
        if (e.getProject() != null) {
            System.err.println("Failed project: " + e.getProject().getName());
        }
        
        // Analyze failure cause
        Throwable cause = e.getCause();
        if (cause instanceof PluginExecutionException) {
            PluginExecutionException pluginError = (PluginExecutionException) cause;
            System.err.println("Plugin failure: " + pluginError.getPlugin().getArtifactId() +
                ":" + pluginError.getMojoExecution().getGoal());
        } else if (cause instanceof MojoFailureException) {
            System.err.println("Mojo reported failure: " + cause.getMessage());
        }
        
    } catch (LifecycleNotFoundException e) {
        System.err.println("Unknown lifecycle: " + e.getLifecycleId());
        System.err.println("Available lifecycles: default, clean, site");
        
    } catch (PluginNotFoundException e) {
        System.err.println("Required plugin not found: " + e.getPlugin().getArtifactId());
        System.err.println("Add plugin to project POM or check plugin repositories");
    }
}

Repository Exceptions

ArtifactTransferFailedException

Exception for artifact transfer failures.

public class ArtifactTransferFailedException extends Exception {
    /**
     * Create artifact transfer failed exception.
     *
     * @param artifact artifact that failed to transfer
     * @param repository repository involved in transfer
     * @param message error message
     */
    public ArtifactTransferFailedException(Artifact artifact, ArtifactRepository repository, String message);
    
    /**
     * Create artifact transfer failed exception with cause.
     *
     * @param artifact artifact that failed to transfer
     * @param repository repository involved in transfer
     * @param message error message
     * @param cause underlying cause
     */
    public ArtifactTransferFailedException(Artifact artifact, ArtifactRepository repository, 
                                          String message, Throwable cause);
    
    /**
     * Get artifact that failed to transfer.
     *
     * @return artifact instance
     */
    public Artifact getArtifact();
    
    /**
     * Get repository involved in transfer.
     *
     * @return artifact repository
     */
    public ArtifactRepository getRepository();
}

ArtifactDoesNotExistException

Exception when a requested artifact does not exist.

public class ArtifactDoesNotExistException extends Exception {
    /**
     * Create artifact does not exist exception.
     *
     * @param artifact artifact that does not exist
     * @param repository repository that was searched
     */
    public ArtifactDoesNotExistException(Artifact artifact, ArtifactRepository repository);
    
    /**
     * Create artifact does not exist exception with message.
     *
     * @param artifact artifact that does not exist
     * @param repository repository that was searched
     * @param message error message
     */
    public ArtifactDoesNotExistException(Artifact artifact, ArtifactRepository repository, String message);
    
    /**
     * Get artifact that does not exist.
     *
     * @return artifact instance
     */
    public Artifact getArtifact();
    
    /**
     * Get repository that was searched.
     *
     * @return artifact repository
     */
    public ArtifactRepository getRepository();
}

Repository Exception Handling Example:

import org.apache.maven.repository.ArtifactTransferFailedException;
import org.apache.maven.repository.ArtifactDoesNotExistException;

public void handleRepositoryOperations(RepositorySystem repositorySystem,
                                     RepositorySystemSession session,
                                     List<RemoteRepository> repositories) {
    Artifact artifact = new DefaultArtifact("com.example", "missing-artifact", "jar", "1.0.0");
    
    try {
        ArtifactRequest request = new ArtifactRequest();
        request.setArtifact(artifact);
        request.setRepositories(repositories);
        
        ArtifactResult result = repositorySystem.resolve(session, request);
        
        if (result.isResolved()) {
            System.out.println("Artifact resolved: " + result.getArtifact().getFile());
        }
        
    } catch (ArtifactResolutionException e) {
        System.err.println("Artifact resolution failed: " + e.getMessage());
        
        // Check for specific causes
        for (Exception cause : e.getResult().getExceptions()) {
            if (cause instanceof ArtifactDoesNotExistException) {
                ArtifactDoesNotExistException notFound = (ArtifactDoesNotExistException) cause;
                System.err.println("Artifact not found in repository: " + 
                    notFound.getRepository().getId());
                
            } else if (cause instanceof ArtifactTransferFailedException) {
                ArtifactTransferFailedException transferFailed = (ArtifactTransferFailedException) cause;
                System.err.println("Transfer failed from repository: " + 
                    transferFailed.getRepository().getId());
                System.err.println("Transfer error: " + transferFailed.getMessage());
                
                // Check for network issues
                if (transferFailed.getCause() instanceof ConnectException) {
                    System.err.println("Network connection failed - check repository URL and connectivity");
                } else if (transferFailed.getCause() instanceof UnknownHostException) {
                    System.err.println("Cannot resolve repository host - check DNS and repository URL");
                }
            }
        }
        
        // Suggest fallback strategies
        System.err.println("Suggestions:");
        System.err.println("- Check artifact coordinates");
        System.err.println("- Verify repository URLs and accessibility");
        System.err.println("- Check network connectivity");
        System.err.println("- Add additional repositories if needed");
    }
}

Exception Handling Best Practices

Comprehensive Error Handling Strategy

public class MavenErrorHandler {
    
    public void handleMavenBuild(Maven maven, MavenExecutionRequest request) {
        try {
            MavenExecutionResult result = maven.execute(request);
            
            if (result.hasExceptions()) {
                categorizeAndHandleExceptions(result.getExceptions());
            } else {
                logSuccessfulBuild(result);
            }
            
        } catch (Exception e) {
            handleUnexpectedException(e);
        }
    }
    
    private void categorizeAndHandleExceptions(List<Throwable> exceptions) {
        Map<Class<?>, List<Throwable>> categorized = exceptions.stream()
            .collect(Collectors.groupingBy(Throwable::getClass));
        
        // Handle each exception category
        categorized.forEach(this::handleExceptionCategory);
        
        // Generate summary report
        generateErrorReport(exceptions);
    }
    
    private void handleExceptionCategory(Class<?> exceptionType, List<Throwable> exceptions) {
        if (ProjectBuildingException.class.isAssignableFrom(exceptionType)) {
            handleProjectBuildingExceptions(exceptions);
        } else if (PluginExecutionException.class.isAssignableFrom(exceptionType)) {
            handlePluginExecutionExceptions(exceptions);
        } else if (DependencyResolutionException.class.isAssignableFrom(exceptionType)) {
            handleDependencyResolutionExceptions(exceptions);
        } else if (LifecycleExecutionException.class.isAssignableFrom(exceptionType)) {
            handleLifecycleExecutionExceptions(exceptions);
        } else {
            handleGenericExceptions(exceptions);
        }
    }
    
    private void handleProjectBuildingExceptions(List<Throwable> exceptions) {
        System.err.println("=== PROJECT BUILDING ERRORS ===");
        
        for (Throwable exception : exceptions) {
            ProjectBuildingException pbe = (ProjectBuildingException) exception;
            System.err.println("Project: " + pbe.getProjectId());
            System.err.println("POM: " + pbe.getPomFile());
            
            if (pbe.getResults() != null) {
                for (ProjectBuildingResult result : pbe.getResults()) {
                    logModelProblems(result.getProblems());
                }
            }
        }
    }
    
    private void logModelProblems(List<ModelProblem> problems) {
        for (ModelProblem problem : problems) {
            String severity = problem.getSeverity().toString();
            System.err.println("  " + severity + ": " + problem.getMessage());
            
            if (problem.getLineNumber() > 0) {
                System.err.println("    at line " + problem.getLineNumber());
            }
        }
    }
    
    private void generateErrorReport(List<Throwable> exceptions) {
        System.err.println("\n=== BUILD ERROR SUMMARY ===");
        System.err.println("Total errors: " + exceptions.size());
        
        Map<String, Long> errorCounts = exceptions.stream()
            .collect(Collectors.groupingBy(
                e -> e.getClass().getSimpleName(),
                Collectors.counting()));
        
        errorCounts.forEach((type, count) -> 
            System.err.println(type + ": " + count));
    }
}

Types

public interface ModelProblem {
    enum Severity {
        FATAL, ERROR, WARNING
    }
    
    String getMessage();
    Severity getSeverity();
    int getLineNumber();
    int getColumnNumber();
    String getSource();
    Exception getException();
}

public class MojoFailureException extends AbstractMojoExecutionException {
    public MojoFailureException(String message);
    public MojoFailureException(String message, Throwable cause);
    public MojoFailureException(Object source, String shortMessage, String longMessage);
}

public class MojoExecutionException extends AbstractMojoExecutionException {
    public MojoExecutionException(String message);
    public MojoExecutionException(String message, Throwable cause);
    public MojoExecutionException(Object source, String shortMessage, String longMessage);
}

public class PluginConfigurationException extends Exception {
    public PluginConfigurationException(ComponentDescriptor componentDescriptor, String message);
    public PluginConfigurationException(ComponentDescriptor componentDescriptor, String message, Throwable cause);
}

public class PluginContainerException extends Exception {
    public PluginContainerException(String message);
    public PluginContainerException(String message, Throwable cause);
}

public class ArtifactResolutionException extends Exception {
    public ArtifactResolutionException(List<ArtifactResult> results);
    public ArtifactResolutionException(List<ArtifactResult> results, String message, Throwable cause);
    
    public List<ArtifactResult> getResults();
}

public class DependencyCollectionException extends Exception {
    public DependencyCollectionException(CollectResult result);
    public DependencyCollectionException(CollectResult result, String message);
    
    public CollectResult getResult();
}

Install with Tessl CLI

npx tessl i tessl/maven-org-apache-maven--maven-core

docs

core-execution.md

exception-handling.md

index.md

lifecycle-management.md

plugin-system.md

project-management.md

repository-system.md

tile.json