Documentation

File uploads fail for filenames with special characters in AEM Forms

Last update: Thu Oct 16 2025 00:00:00 GMT+0000 (Coordinated Universal Time)

File uploads through Adaptive Forms in AEM Forms On-prem 6.5 fail when filenames contain special or Unicode characters. This issue occurs during multipart form submissions that use a custom submit action that stores files in Azure Blob Storage via a cloud connector. During file extraction in the submission handler, methods like part.getName() incorrectly replace Unicode characters with “???” or “?”, disrupting filename mapping and preventing successful uploads.

To fix this, use the getSubmittedFileName() method to accurately retrieve filenames with special characters and ensure reliable uploads to Azure Blob Storage.

Description description

Environment

  • Product: AEM Forms
  • Version: v6.5

Issue/Symptoms

  • Filenames with special characters are displayed as “???” or “?” when retrieved using part.getName().
  • The request.getParts() method doesn’t return all attachments if filenames contain Unicode characters.
  • Uploads fail for files with special Unicode characters in their names, especially during multipart form submissions.
  • Incorrect filename encoding affects blob storage operations, preventing successful uploads.

Resolution resolution

To resolve the issue, update the file upload logic to use getSubmittedFileName() instead of getName(). This ensures filenames with special or Unicode characters are correctly retrieved and processed. Follow these steps:

  1. Replace all calls to part.getName() with part.getSubmittedFileName() in your code. This method retrieves the original filename, including special or Unicode characters.

  2. Test the updated code using sample files with various types of filenames to confirm correct behavior. For example,

    code language-none 
    // Before (problematic) String filename = part.getName();     // After (fixed) String filename = part.getSubmittedFileName();

  3. Deploy the updated code to production and verify that file uploads work across all environments and platforms.

By making this change, filenames are accurately processed regardless of character set, enabling successful uploads even for files with special or Unicode characters.

Importing and exporting assets to AEM Forms in AEM 6.5 User Guide

recommendation-more-help
3d58f420-19b5-47a0-a122-5c9dab55ec7f