Knowledge Base
Knowledge Base
  • Login
Font Size:
Ask Joget AI

Unable to upload files with non-ASCII characters in file name

Description

Attempting to upload a file with non-ASCII characters in the filename, such as Chinese characters, in the Joget File Upload form element fails. If no validator is selected, the form is submitted, but no file is successfully uploaded when viewing or editing the record.

The following error message is returned in the system logs:

Error

java.io.IOException: File transfer failed Caused by: java.nio.file.InvalidPathException: Malformed input or input contains unmappable characters Path: /opt/joget/wflow/app_tempfile/.../<Non-ASCII FILENAME>.jpg

If Mandatory Validator is selected, the following error message is returned in the form:

Error
Missing required value

Cause

The issue is related to the system's character encoding configuration. By default, the environment was set to ANSI_X3.4-1968, which does not support non-ASCII characters. To resolve this, the encoding must be changed to UTF-8 by updating the following:

  • JAVA_OPTS: Add -Dsun.jnu.encoding=UTF-8

  • LANG environment variable: Set to LANG=C.UTF-8

These changes ensure proper handling of filenames with Chinese, Arabic, Cyrillic, Japanese, and other non-ASCII characters.

Solution

Before beginning this workflow, check if your environment is already running UTF-8 encoding. If it is not, follow these steps:

To enable support for filenames containing non-ASCII characters in Joget, update the system's character encoding configuration as follows:

  1. Navigate to the Joget DX installation page. The default location is as follows: C:\Joget-DX9-Enterprise.
  2. Right-click the joget-start batch file and click Edit in Notepad.
  3. Add the following script to the batch file: -Dsun.jnu.encoding=UTF-8
set JAVA_OPTS=-Xmx2048M -Dwflow.home=./wflow/ -javaagent:./wflow/aspectjweaver-1.9.22.jar -Dsun.jnu.encoding=UTF-8
 -javaagent:./wflow/glowroot/glowroot.jar
  1. Save the batch file.
  2. Set System Language Environment Variable to LANG=C.UTF-8:
    • Windows:
      1. Open System Properties > Advanced > Environment Variables.
      2. Under System variables, click New.

      3. Set the following properties:

        • Variable name: LANG

        • Variable value: C.UTF-8

      4. Click OK and restart your system or application.
    • Linux:

      1. System-wide: Edit /etc/default/locale or /etc/environment
        Add or modify the line:

        LANG=C.UTF-8

        Or

      1. User-specific: Add to your shell profile (e.g., ~/.bashrc, ~/.zshrc)

        export LANG=C.UTF-8
      2. Then run:
        source ~/.bashrc
    • Docker:
      1. In Dockerfile, add:
        ENV LANG=C.UTF-8
ENV JAVA_OPTS="-Dsun.jnu.encoding=UTF-8"
      2. After starting the container, you can verify the settings:
        docker exec -it <container_id> bash
echo $LANG
echo $JAVA_OPTS

        Ensure the output shows:

        C.UTF-8
-Dsun.jnu.encoding=UTF-8
  1. Restart Joget.

After saving the changes, restart Joget and attempt to upload a file with Chinese characters in the filename to confirm resolution.

Created by Debanraj Ravindran Last modified by Debanraj Ravindran on Apr 24, 2026
Tags:
Previous Problem NextDiagnosing Slow Pages