Introduction
Organizations migrating applications from Pega Platform 8.6 on-premise to Pega Cloud 25 may encounter issues where legacy customizations no longer behave as expected after platform upgrades. One such issue involved document uploads failing whenever users selected document types containing accented or special characters. This article describes how a customized version of the OOTB pzMultiFilePath control caused document upload failures after migration, explains the root cause, documents the temporary workaround that restored functionality, and provides recommendations for avoiding similar issues in future platform upgrades. The investigation and solution were led by @Giovani
The Problem
Following a migration from Pega Platform 8.6 to Pega Cloud 25, users reported intermittent failures when uploading attachments. The issue only occurred when the selected document type contained accented or special characters. For example, a value such as Licença Ambiental was displayed after the UI refresh as Licença Ambiental, a classic mojibake pattern caused by a mismatch between UTF-8 and ISO-8859-1/CP1252 interpretation of the same byte stream.
Although the selected value remained correct in memory during processing, it became corrupted after the attachment section was refreshed on the user interface. As a result, the upload logic could no longer correctly match the selected document type, causing the attachment process to fail.
During the investigation, it was determined that the application was not using the standard OOTB pzMultiFilePath control. Instead, it relied on a customized implementation originally created to support opening the file selector through a modal dialog. After the upload completed, the custom implementation executed a section refresh using pega.u.d.reloadSection(...). The problem became visible only after the migration because the customized component had not evolved alongside the changes introduced in newer platform versions.
The Solution
Was performed a detailed comparison between the customized implementation and the current OOTB implementation delivered with the platform. The analysis revealed a significant difference in how form encoding was configured during file upload operations.
The customized control was still relying on the older, internal encoding utilities:
pega.c.AttachUtil.setEncodingFileUpload(...)
pega.c.AttachUtil.setEncodingForm(...)
The OOTB implementation in the newer platform version, however, had been updated to use the context-level encoding API:
pega.ctx.setFormEncoding(true);
pega.ctx.setFormEncoding(false);
To mitigate the production impact, the custom control was modified to align with the encoding approach used by the current OOTB implementation. The temporary workaround consisted of replacing the legacy encoding calls with pega.ctx.setFormEncoding(true) before the form submission and pega.ctx.setFormEncoding(false) immediately afterward, restoring the default behavior.
After applying the change:
| Before the fix | After the fix |
|---|---|
| Accented characters corrupted after UI refresh | Special and accented characters preserved correctly |
| Document type value mismatched during upload | Document type values remained consistent during UI refresh operations |
| Attachment upload failed silently | Attachment uploads completed successfully |
| Issue reproducible on demand | Issue could no longer be reproduced during validation testing |
It is important to note that this change was intentionally treated as a temporary workaround rather than a permanent architectural solution.
Root Cause
The root cause was not the migration itself, nor the Pega Cloud environment. The issue occurred because a customized OOTB control had diverged from the standard platform implementation over time. As Pega Platform evolved, including the transition of Pega Cloud environments to a Tomcat-based, Jakarta EE architecture, the framework updated how encoding is managed during form submissions and file uploads. Those updates were automatically incorporated into the OOTB pzMultiFilePath control but were never applied to the customized version, since a customization freezes its logic at the point it was created.
Consequently, the custom implementation continued using an outdated encoding mechanism that was no longer fully compatible with the behavior expected by newer platform versions. Pega’s own migration remediation guidance confirms that on Pega Cloud, the underlying Tomcat server can default to ISO-8859-1 for web requests unless the client explicitly signals UTF-8, which is precisely the gap that pega.ctx.setFormEncoding closes.
This scenario highlights a well-known upgrade risk: customizations of OOTB rules do not automatically inherit platform enhancements, bug fixes, performance improvements, or compatibility updates delivered in subsequent releases. This aligns with Pega’s long-standing guardrail recommendations, which encourage minimizing customization of OOTB artifacts and favoring extension over modification. The more a customization diverges from the OOTB implementation, the greater the risk that future platform changes will introduce unexpected behavior.
Conclusion
This issue demonstrates how legacy customizations can become a hidden source of migration and upgrade challenges. Although the immediate problem was resolved by updating the custom control to use the same encoding mechanism adopted by the current OOTB implementation, the preferred long-term approach is to eliminate unnecessary customizations and return to the standard platform component whenever feasible.
Key takeaways include:
- Validate all customized OOTB components during migration projects.
- Compare customized implementations against the latest OOTB version when troubleshooting upgrade-related issues.
- Treat customizations of foundational UI controls, such as attachment/upload utilities, as potential upgrade risks.
- Prefer OOTB components whenever possible to reduce long-term maintenance effort and to inherit future compatibility and security fixes automatically.
- Ensure any custom control that touches encoding, file storage, or form submission logic is re-validated whenever the underlying Pega Platform version changes, especially across major architecture shifts such as the move to Jakarta EE.
The temporary workaround restored functionality, but the strategic recommendation remains to migrate back to the OOTB pzMultiFilePath control after all environments are upgraded and fully validated.
Acknowledgements
Special thanks to @Giovani for leading the investigation, identifying the encoding discrepancy between the customized and OOTB implementations, implementing the workaround, validating the fix, and documenting the long-term remediation strategy.