Applies to Pega Platform 7.2-8.6
This article provides answers to frequently asked questions about the file upload and download functionality of the Pega engine. It also guides you on how to upload and download files.
How to address file size issues while uploading a file? The following error occurs while uploading a file, “User attempted to upload a file larger than 1024 MB. Please contact the System Administrator.”
How to set the maximum file size limit?
Is uploading a file of size 4GB allowed?
What is the reason for the occurrence of Status 413 response with a blank page on the UI?
How to debug issues that occur when uploading files with names containing Unicode characters (Multi-byte)?
What are the artifacts that need to be collected when an issue with file upload occurs?
Why are files with same names overridden during parallel uploads?
What causes an attachment to become corrupt? How to address this issue?
How to debug issues that occur while downloading a file?
What does the aSendForDownload parameter in the sendFile API signify?
Is it possible to download a file with name that contains special characters?
Why does the Content-Disposition header display in the response but not in the file content?
Why is that the Content headers populate correctly in the response but the file content does not display?
What are the artifacts that need to be collected before creating a Support Request when an issue with file download occurs?
Why do users’ proxies reject requests when file names contain special characters?
File upload
The Pega engine runs the following steps when you upload a file:
-
The browser sends FormData (multi-part request) to the Pega server. The data is read from the request and the file is saved at the following temporary directory location:
<pegaTempDir>/StaticContent/global/ServiceExport -
The file is read from the temporary location and saved to the database. An attachment or a link is generated in the work object when an attachment is added to the work object.
File upload FAQs
How to address file size issues caused by the error, User attempted to upload a file larger than 1024 MB. Please contact the System Administrator?
Pega has a file size limit. The exception occurs on uploading a file whose size is larger than the available limit.
For releases prior to Pega 8.5, the default file size is 1024 MB.
For Pega 8.5 and later releases, the default file size is 1536 MB.
How to set the maximum file size limit?
Set the file size limit using the initialization/maximumfileuploadsizemb setting in the prconfig.xml file.
For example, to limit the file size to a maximum of 10 MB, use the following code:
<env name="initialization/maximumfileuploadsizemb" value="10"/>
See the default file size limits in How to address file size issues caused by the error User attempted to upload a file larger than 1024 MB. Please contact the System Administrator?
Is uploading a file of size 4GB allowed?
The maximum size limit of a file that can be uploaded is 2GB.
If the initialization/maximumfileuploadsizemb setting in prconfig.xml is set to a value greater than or equal to 2GB (2048 MB), then the allowed size (file size within the limit) is reset to the default value.
What is the reason for the occurrence of Status 413 response with a blank page on the UI?
When you attempt to upload a file that is larger than the configured size, the Pega engine rejects the HTTP request with Status 413 response.
How to debug issues that occur when uploading files with names containing Unicode characters (multibyte)?
You cannot upload files with names containing Unicode characters (multibyte) because of character set mismatch at the Operator System level or Application level.
To address the issue, verify the file name in the ServiceExport(<pegaTempDir>/StaticContent/global/ServiceExport) directory (Pega temp location) to verify that the file is saved correctly in the file system.
If the file is saved correctly, then the issue might be with the file upload activities. Go to My Support Portal and create a support case For an issue I’m having (INC) for this issue with the required artifacts.
If the file is written incorrectly in the file system, perform the following steps:
-
Verify whether it is possible to create a file with a same name (the name provided during file upload).
-
Pass the -Dfile.encoding=UTF-8 Java Virtual Machine (JVM) argument.
-
Restart the server.
What are the artifacts that need to be collected when an issue with file upload occurs?
When an issue with file upload occurs, collect the following artifacts before creating a support case in My Support Portal For an issue I’m having (INC):
-
PegaRULES Log file
-
Fiddler trace
-
Pega trace after adding pxRequestor and pxThread to additional pages in Tracer Settings
-
Verification that the file is stored correctly in the ServiceExport (<pegaTempDir>/StaticContent/global/ServiceExport) directory
Why are files with same names overridden during parallel uploads?
Files uploaded with same names are overridden by one another. This occurs because the ServiceExport directory is common for all the users. If two users upload files with same name, then one of the user's files is overridden by the other file. This issue occurs on Pega 7.4. However, the issue is addressed in Pega 8.1 by adding a unique identifier to the file while storing it in the temporary directory (Service Export).
This issue is addressed in the following Pega Platform versions:
-
Pega 8.1.6 and later patch versions
-
Pega 8.2.3 and later patch versions
-
Pega 8.3.1 and later patch versions
-
Pega 8.4. and later patch versions
What causes an attachment to become corrupt? How to address this issue?
A different process terminates the file input stream handle while reading the file content from the temporary (ServiceExport) location before attaching it (the file content read) to the work object. Antivirus software might terminate the file input stream handle. If this happens, disable the antivirus scans for the ServiceExport (temporary location) directory.
File download
Here is what happens when you download a file:
-
You fetch a file or file content from the repository based on the document key.
-
The file content goes to the browser.
-
The Pega engine uses the sendFile API to send the content from the server to the browser. The sendFile API is a simple API that is invoked by an activity that sets the file headers (for example, Content-Disposition, Content-Type, .. so on) on the pxRequestor.pyHTTPResponseHeaders Requestor page and file handle or file content on the pxThread page.
-
The Pega engine uses the headers or metadata while sending the response to the browser.
No issue occurs with the sendFile API when both the following conditions are met:
- The file download request contains Content-Disposition and Content-Type headers.
- The response body contains file content.
File download FAQs
How to debug issues that occur while downloading a file?
Content-Disposition and Content-Type headers are part of Response headers. Response of a File download request must contain the Content- Disposition and Content-Type headers. This can be verified from the Fiddler or Network trace.
The values of Content-Disposition and Content-Type headers are as follows:
-
content-disposition : attachment:filename=”dummy.pdf”
-
content-type = application/octet-stream
What does the aSendForDownload parameter in the sendFile API signify?
The aSendForDownload parameter signifies that the sendFile API is used to download a file or to have an inline view of a file. If the flag (parameter) is set to True then Content-Type must be application/octet-stream and the Content-Disposition must be 'attachment;filename......'. If not, Content-Type is dependent on MIME type of file extension.
Is it possible to download a file with name that contains special characters?
No. When a file name contains special characters, Pega sets the original file name in the Content-Disposition header. Some of the Web or App servers and proxies reject the requests if any of the Response headers contains non-ASCII characters. This product bug is addressed to set the encoded file name instead of the original file name in the Content-Disposition header.
This issue is addressed in the following patch versions:
-
Pega 8.5 and later patch versions
-
Pega 8.4.2 and later patch versions
-
Pega 8.3.4 and later patch versions
-
Pega 8.2.7 and later patch versions
Why does the Content-Disposition header display in the response but not in the file content?
This issue occurs when you configure your own repository for file download following the instructions in Creating a custom repository type article. This issue also occurs when you override the pyGetFile activity to fetch the file content from your own custom repository.
Why is it that the Content headers populate correctly in the response but the file content does not display?
This issue occurs when you override the pyGetFile activity while performing the Show-Page activity method that populates the pxThread.pyXMLStream property. When the pxThread.pyXMLStream property populates, the engine does not consider the pxRequestor.pyFileDownload property and the file content is not set in the response object. Hence, the file content does not display.
In this case, open the Pega Tracer and trace the request by adding pxRequestor and pxThread Clipboard pages to the additional pages to trace in Tracer Settings. Verify that the pxThread.pyXMLStream property has populated and also check the step in which it is populated.
What are the artifacts that need to be collected when an issue with file download occurs?
When an issue with file download occurs, collect the following artifacts before creating a support case in My Support Portal For an issue I’m having (INC):
-
PegaRULES Log file
-
Application Server Log files (for example, Catalina.log for Tomcat)
-
Fiddler Trace
-
Pega trace after adding pxRequestor and pxThread to additional pages in Tracer Settings
Why do users’ proxies reject requests when file names contain special characters?
Pega sends an extension filedownload HTTP header that represents the exact file name stored in a repository (for example, AWS S3).
Filedownload header contains plain non-ASCII characters that cause security violation issues. This header is used internally by Pega. This header must not be a part of Response headers. Hence, a hotfix is provided by Pega to not set the filedownload header in the file download HTTP response.
The issue is addressed in the following patch versions:
-
Pega 8.2.6 and later patch versions
-
Pega 8.3.3 and later patch versions
-
Pega 8.4.1 and later patch versions
-
Pega 8.5 and later patch versions
