Contents show

Overview of the Problem

File upload failures in ColdFusion occur when a user attempts to upload a file through a web form and the server either rejects it, times out, or errors before saving the file. Symptoms range from generic “500 Internal Server Error” pages to ColdFusion-specific messages like “There was an error uploading the file” or “POST data exceeds allowed limit.” These failures happen because multiple layers—browser, web server (IIS/Apache), connectors (BonCode/AJP), ColdFusion Administrator settings, application code, filesystem permissions, and Security software—must all agree to accept, buffer, and write the file. Any misconfiguration or bottleneck along this path can cause the upload to fail.

How ColdFusion Handles File Uploads (Quick Context)

When a user submits a form with a file:

The browser sends a multipart/form-data POST request.
The web server (IIS/Apache) checks request filtering limits and buffers an initial portion of the upload.
The connector (BonCode/AJP or mod_proxy_ajp) passes the request to the ColdFusion (Tomcat) runtime.
ColdFusion parses the multipart request and writes the file to a temp location (java.io.tmpdir) during processing.
Your CFML code (often cffile action=”upload”) saves the file to a final destination and performs validations.

A failure at any step—size limits, buffer sizes, timeouts, temp directory problems, permissions, or code-level validations—will abort the upload.

Possible Causes

Environment limits (web server, connector, ColdFusion Admin)
Application code mistakes (missing enctype, bad cffile usage, unhandled exceptions)
Filesystem path or permissions issues
Security software or WAF blocking the request
Network slowdowns or timeouts
Memory or JVM heap pressure during post-processing
MIME type / extension validation failures

Common Error Messages and Where to Look

In ColdFusion logs (cfusion/logs):
- exception.log: POST data exceeds the maximum limit, java.lang.OutOfMemoryError
- application.log or coldfusion-error.log: There was an error uploading the file
Web Server logs:
- IIS: HTTPERR, u_exYYMMDD.log, W3SVC logs
- Apache: error_log, access_log
Browser or client-side: 413 Payload Too Large, 500 Server Error, connection reset

Example ColdFusion log entries:

coldfusion.filter.FormPostBufferFilter$PostSizeLimitExceededException: POST data exceeds the maximum limit.
coldfusion.tagext.io.FileUtils$InvalidMIMETypeException: The uploaded file’s MIME type is not allowed.
java.lang.OutOfMemoryError: Java Heap space

Step-by-Step Troubleshooting Guide

Step 1: Reproduce and Capture the Error

Reproduce the problem with a known test file and note:
- File size
- File type/MIME
- Upload time until failure
- The exact error message or HTTP status
Check ColdFusion logs (exception.log, application.log) immediately after a failure.
Check web Server logs for 413 or request filtering blocks.
If a proxy/load balancer is used, inspect its logs for drops or size limits.

Step 2: Verify Your Form and CFML Upload Code

The form must specify enctype and method POST.
Ensure the input name matches your cffile field.

Example HTML form:

Basic cffile usage:

CFScript equivalent:

try {
fileResult = fileUpload(
expandPath(“/uploads/incoming”),
“myfile”,
“makeunique”,
“image/jpeg,image/png,application/pdf”
);
writeDump(fileResult);
} catch (e) {
writeOutput(“Upload failed: ” & e.message);
}

Ensure the destination folder exists and is writable by the ColdFusion service user.
If you use accept, ensure the MIME types are correct; otherwise, ColdFusion will reject the file with an InvalidMIMEType exception.

Step 3: Check Size Limits Across the Stack

Uploads can fail if any component’s size limit is exceeded. Increase each limit as needed, starting with the smallest.

IIS requestFiltering (maxAllowedContentLength in bytes):

IIS uploadReadAheadSize (bytes read before passing to CF):

Apache httpd (per vhost or global):

LimitRequestBody 104857600 # 100 MB

BonCode (IIS-to-Tomcat connector), BonCodeAJP13.settings:

MaxPostSize=104857600 # 100 MB; -1 or 0 may indicate unlimited, but set realistically

ColdFusion Administrator:
- Settings > Request Size Limits:
  - Maximum size of POST data (match or exceed web server limit)
  - Maximum number of POST parameters (raise if large multi-upload forms use many fields)
- Server settings > Settings:
  - Request Timeout (ensure enough time for slow uploads)
Application-level request timeout if using Application.cfc:

this.requestTimeout = createTimeSpan(0,0,5,0); // 5 minutes

Tip: Keep limits consistent and slightly higher as you move downstream (IIS/Apache ≤ Connector ≤ ColdFusion).

Step 4: Verify Temp and Destination Directories and Permissions

ColdFusion writes uploads to a temp directory (java.io.tmpdir) while processing. If that directory is missing or lacks permissions, uploads fail.

Discover directories at runtime:

Ensure both temp and destination directories:
- Exist
- Have sufficient free disk space
- Are writable by the ColdFusion service user (Windows service account or Linux user)
On Windows + IIS: the CF service (e.g., “ColdFusion 2021 Application Server” account) needs NTFS write permission.
On Linux: chown/chmod the path to the user running CF (often cfuser).

Step 5: Validate MIME Types and Extensions Correctly

Using accept on cffile/fileUpload enforces whitelist MIME types.
Cross-check server-reported MIME with a trusted function:

Also validate the file extension and size:

Note: Never trust only client-side validation. Always re-validate on the server.

Step 6: Monitor Memory and Post-Processing

If the upload succeeds but post-upload processing fails (e.g., image manipulation, antivirus scan, resizing), you might see:

java.lang.OutOfMemoryError in logs
Slow or stalled requests then timeouts

Mitigations:

Increase JVM heap (-Xmx) cautiously if needed.
Avoid loading entire large binaries into memory; process streams or use efficient APIs.
For images, resize with cfimage in a memory-conscious way or use external tools where appropriate.
Ensure antivirus scanning is efficient and non-blocking.

Step 7: Address Timeouts and Slow Networks

Large or slow uploads can hit timeouts:

Increase request timeout at the application level or CF Administrator.
For proxies/load balancers, raise idle connection timeouts.
If the client’s connection is slow, provide chunked uploads or resumable upload patterns.

Step 8: Check Security Software and WAF Rules

Web Application Firewalls or security modules (mod_security) may block certain file types or patterns.
Antivirus may quarantine temp files during upload.
Temporarily disable or create whitelisting rules for the upload path and test again.
Review WAF logs for rule hits and adjust policies accordingly.

Step 9: Consider Multiple Files and Chunked Uploads

For multiple files, ensure POST parameter limits are high enough and form fields are unique.
For very large files, use chunked/resumable uploads with client libraries and assemble server-side.
Validate and store each chunk safely; verify final checksum.

Quick Cause / Solution Reference

File too large
- Solution: Increase IIS/Apache max size, BonCode MaxPostSize, ColdFusion POST size limit.
Missing form enctype
- Solution: Ensure enctype=”multipart/form-data” in the form.
Destination or temp directory not writable
- Solution: Fix directory permissions for CF service user; ensure disk space.
MIME type/extension not allowed
- Solution: Update accept list; validate with fileGetMimeType and extension checks.
Request timeout
- Solution: Increase request timeout in Application.cfc or CF Admin; tune proxy timeouts.
Antivirus/WAF block
- Solution: Whitelist upload path or file types; tune mod_security rules; exclude CF temp folder.
Connector/Web server buffering too small
- Solution: Increase uploadReadAheadSize (IIS), adjust Apache buffering, and connector MaxPostSize.
JVM memory exhausted during processing
- Solution: Optimize post-processing, increase heap, process streams/chunks, avoid unnecessary in-memory copies.

Common mistakes and How to Avoid Them

Forgetting enctype=”multipart/form-data”
- Avoidance: Always include this attribute on File upload forms.
Trusting only client-side checks
- Avoidance: Implement server-side validation for MIME type, extension, and size.
Using user-supplied filenames directly
- Avoidance: Use nameConflict=”makeunique” or rename to a safe, normalized server filename.
Storing uploads inside the webroot
- Avoidance: Store outside webroot and serve via a controlled endpoint.
Misaligned size limits across layers
- Avoidance: Keep IIS/Apache, connector, and ColdFusion limits consistent and documented.
Not handling exceptions
- Avoidance: Wrap uploads in try/catch and log detailed errors.
Ignoring permissions and free space
- Avoidance: Monitor disk usage; validate permissions on temp and destination paths.

Prevention Tips / Best practices

Enforce strict whitelist of MIME types and extensions at both cffile and code validation levels.
Limit maximum file size in both UI and server Configuration; provide user feedback before upload starts.
Store uploads outside the webroot; serve via a secure Download handler with authorization checks.
Generate unique filenames (UUIDs) and maintain metadata in a database.
Scan files with antivirus asynchronously to avoid blocking user requests.
Implement Rate limiting and throttling to protect against abuse.
Provide resumable/chunked uploads for large files.
Add robust logging: record user ID, IP, filename, size, MIME, and outcome.
Monitor logs and metrics for spikes in failures; set alerts for high 413/500 error rates.
Regularly test uploads after server patches or Configuration changes.

Code Patterns and Configuration Examples

A Defensive Upload Handler (Tags)

<!--- Basic form checks --->
<cfif NOT structKeyExists(form, "myfile") OR len(form.myfile) EQ 0>
    <cfthrow message="No file was uploaded." />
</cfif>

<!--- Upload --->
<cffile action="upload"
        destination="#expandPath('/secure_uploads/incoming')#"
        fileField="myfile"
        nameConflict="makeunique"
        accept="image/jpeg,image/png,application/pdf"
        result="fileResult" />

<!--- Server-side validation --->
<cfset allowedMimes = "image/jpeg,image/png,application/pdf">
<cfset allowedExts = "jpg,jpeg,png,pdf">
<cfset maxBytes    = 50*1024*1024> <!--- 50 MB --->

<cfset mime = fileGetMimeType(fileResult.serverFile)>
<cfif NOT listFindNoCase(allowedMimes, mime)>
    <cfthrow message="Disallowed MIME type: #encodeForHTML(mime)#" />
</cfif>

<cfif fileResult.fileSize GT maxBytes>
    <cfthrow message="File exceeds the maximum size limit." />
</cfif>

<cfset ext = listLast(fileResult.serverFile, ".")>
<cfif NOT listFindNoCase(allowedExts, ext)>
    <cfthrow message="Disallowed file extension." />
</cfif>

<!--- Move to final storage outside webroot --->
<cfset finalPath = expandPath("/data/uploads/#createUUID()#.#lcase(ext)#")>
<cffile action="rename" source="#fileResult.serverDirectory#/#fileResult.serverFile#" destination="#finalPath#">

<cfoutput>Upload successful.</cfoutput>

Upload failed. Please try again later.

IIS web.config Snippet for Larger Uploads

Apache VirtualHost Snippet

<VirtualHost *:80>
ServerName example.com
DocumentRoot /var/www/example
LimitRequestBody 157286400 # 150 MB

Proxy/connector config here…

Application.cfc: Request Timeout and Security Hints

component {
this.name = “MyApp”;
this.requestTimeout = createTimeSpan(0,0,10,0); // 10 minutes

// Optionally implement onError to log unexpected failures
public void function onError(any exception, string eventName) {
    cftrace(type="information", var=exception);
}

}

Key Takeaways

A file upload passes through browser, web server, connector, ColdFusion, and your code; any layer can block it.
Align size limits across IIS/Apache, connectors (BonCode), and ColdFusion Administrator to prevent 413/POST limit errors.
Validate file type, extension, and size server-side; never trust client declarations.
Ensure temp and destination directories are writable and have sufficient space.
Timeouts, antivirus/WAF rules, and memory-intensive post-processing are common hidden culprits—monitor logs and tune accordingly.

FAQ

Why do I get “POST data exceeds the maximum limit” even after raising ColdFusion’s POST size?

This usually means another layer (IIS requestFiltering maxAllowedContentLength, Apache LimitRequestBody, or the connector’s MaxPostSize) still has a smaller limit. Verify and raise limits consistently from web server to connector to ColdFusion.

How can I allow only images to be uploaded securely?

Use cffile accept to whitelist image MIME types, and also validate server-side with fileGetMimeType and allowed extensions. Consider using isImageFile on the saved file and scanning with antivirus. Store outside webroot and rename with a UUID.

Uploads of small files work, but large files time out. What should I change?

Increase request timeouts (Application.cfc or CF Admin), raise web server and connector size limits, and confirm network/proxy idle timeouts. If users have slow connections, adopt chunked/resumable uploading to avoid long single requests.

I set permissions on the destination folder, but uploads still fail. What else should I check?

Verify write permissions on the temp directory (getTempDirectory()), ensure adequate disk space, and confirm the account running the ColdFusion service has NTFS/Unix permissions. Also check if antivirus is quarantining temp files during upload.

Why do I see OutOfMemoryError during Image processing after a successful upload?

The upload itself may succeed, but post-processing (e.g., resizing large images) can consume excessive heap. Reduce image dimensions before processing, optimize code to avoid duplicating large binaries in memory, or increase the JVM heap where appropriate.

How to Fix File Upload Failures in ColdFusion

Overview of the Problem

How ColdFusion Handles File Uploads (Quick Context)

Possible Causes

Common Error Messages and Where to Look