How to address issues with 'unmappable characters' ?

Issue

  • We see stacktrace mentioning the following cause:

    java.nio.file.InvalidPathException: Malformed input or input contains unmappable characters: <pathOfFileWithUnmappableCharacters> 
    

Environment

Related Issues

Resolution

The root cause of this issue is most likely due to the encoding used by the JVM running the process.

If the exception appears in the Jenkins logs, the Jenkins master’s JVM is most likely the culprit.
If the exception appears in a build console output, a build agent’s JVM is most likely the culprit.

Check the encoding of the JVM

Check the encoding of the JVM by looking at the following system properties:

  • file.encoding
  • sun.jnu.encoding

The system properties can be found in Jenkins:

  • for the Jenkins master, under Manage Jenkins > System Information
  • for a Jenkins agent, under Manage Jenkins > Manage Nodes > $NODE_NAME > System Information

If the encoding is not UTF-8, this is most likely the root cause of the problem.

Solution

To fix this, add the system properties -Dfile.encoding=UTF-8 -Dsun.jnu.encoding=UTF-8 and restart the process:

  • for the Jenkins master, add the properties as explained in How to add Java arguments to Jenkins? and restart Jenkins
  • for a Jenkins agent, add the properties to the “JVM options” of the agent’s configuration and restart the agent

Check the Locale of the machine running the JVM

If the above solution did not working, it could be that the encoding of the JVM is enforced by the Locale of the underlying OS. If that’s the case, setting the encoding via system properties would have no effect.

Check the Locale of the system by looking at the environment variables:

$ env | grep LANG
LANG=en_US.UTF-8

If the encoding is not <country>.UTF-8 for LANG, it needs be changed.

Note: en_US is for US English language but the language may vary.

Solution

To fix this, change the Locale of the machine and restart the process. Depending on the distribution and the environment, the solution differs. Here are a couple of relevant articles:

Changes made to the locale are applied when a user logs in. You will need to logout and login again for the changes to take effect. Then restart the JVM process.

Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.