How to configure Character Encoding in Maven

How to configure Character Encoding in Maven

Sometimes, when compiling Java files with Maven or building WAR files, encoding errors may occur, as described below

  • File encoding has not been set, using platform encoding UTF-8, i.e., the build is platform-dependent!
  • Maven character encoding source not working

Since Maven reads the source code for building and installing artifacts, it should define the character encoding to read and write files of different encoding types - ASCII, UTF-8, or UTF-16. Maven uses the default encoding of the running platform, i.e., ISO-8859-1.

This post helps to assist developers in resolving Maven character encoding issues.

There are multiple ways to configure encoding in Maven projects.

You can check my other posts on maven commands

Configure character encoding in the Maven application

Maven offers project-level properties to set encoding at the application level.

You can define properties such as project.build.sourceEncoding and project.reporting.outputEncoding in the pom.xml to establish encoding settings for the entire application.

<properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
</properties>

The advantage of this approach is that you don’t need to manually define encoding for each plugin you use. Once this encoding is configured using these properties in the pom.xml, all plugins will automatically reuse this configuration.

Change encode to UTF-8 in maven resource plugin

To change the encoding in the Maven Resource Plugin, configure the plugin with UTF-8 encoding using the configuration settings

 <plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-resources-plugin</artifactId>
    <configuration>
      <encoding>UTF-8</encoding>
    </configuration>
  </plugin>

Alternatively, you can set project.build.sourceEncoding to UTF-8 in the project properties.

Configure Command-line maven options

To run Maven goals via the command line, it is necessary to use either the -D option or the MAVEN_OPTS environment variable.

When using Maven with the -D option, you can set environment variables. This is particularly useful for configuring encoding-related properties, as described below

mvn -Dproject.build.sourceEncoding=UTF-8

or

set "MAVEN_OPTS=-Duser.language=fr -Dfile.encoding=UTF-8"
set MAVEN_OPTS= -Dfile.encoding=UTF-8

Encoding in maven compiler plugin

A compiler plugin is used to compile Java source files, and if any characters are present in source files, encoding issues may arise.

Below is the method to set the character encoding to UTF-8 in the Maven Compiler Plugin

<plugins>
      <plugin>
        <artifactId>maven-compiler-plugin</artifactId>
        <version>2.6.0</version>
        <configuration>
          <source>1.8</source>
          <target>1.8</target>
          <encoding>UTF-8</encoding>
        </configuration>
      </plugin>
</plugins>

How to change encoding for the maven test?

When compiling and testing your Java classes, you may encounter encoding issues for lines of code containing UTF-8 characters.

Maven tests are executed using the Maven Surefire Plugin, and to address encoding issues, you need to configure the plugin using the argLine configuration option. This enables the Surefire Plugin to read all files with UTF-8 encoding.

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-surefire-plugin</artifactId>
    <configuration>
        <argLine>-Dfile.encoding=UTF-8</argLine>
    </configuration>
</plugin>

Conclusion

As discussed earlier, changing character encoding from the default to UTF-8 can be done at the global level, plugin level, or command-line level. Additionally, you can update Maven standard properties such as -Dfile.encoding, project.build.sourceEncoding, or project.reporting.outputEncoding in various ways.