File Uploads

What users may upload, how filenames are handled, and the chunked transfer that makes large files work.

Upload Rules

Several settings decide what the platform accepts when somebody uploads a file.

Where to find it

Architect Panel → Configuration:

Site Settings — the File Uploads and Audio/Video Conversion groups

Architect Panel → Data:

File Stores — the stores themselves, and View File Store on a row
Large Uploads — in-progress and stalled upload sessions
File Import Routines — watched sources and their mappings

The settings

Allow files without filenames.
Allow files without extensions.
Replace spaces in filenames.
Force simple file names.
Index document contents.
Public and private upload paths.

Three of these are conveniences. The rest decide whether a hostile upload is a problem.

File scopes constrain the types

Separately from these settings, named scopes list the file types allowed in a particular context. That is where "images only" or "documents only" is expressed, per place rather than for the whole installation.

Use them. An upload field accepting anything is an upload field somebody will use for anything.

Uploads are user-supplied content

The framing that matters. A file is data from somebody you do not control, with a name they chose, in a format they chose. Treat every upload accordingly:

Never trust the name.
Never trust the declared type.
Never serve it back from somewhere it could execute.

Private by default

Anything that is not deliberately public belongs on the private path, served through the platform so permissions apply. A file placed in a public directory is a file with a guessable address and no access control.

Keep names simple

The safe-name setting exists because filenames arrive containing anything a user’s device allowed — accents, emoji, path separators, control characters. Simplifying them avoids problems across operating systems, in URLs, and in downloads.

Set size limits realistically

Large enough for the documents people genuinely need to send, small enough that a mistake is not a storage incident. And remember that large files have their own chunked path — the limit that matters is often not the one you think.

Think about what accumulates

Uploads only grow. Attachments on records that were closed years ago, drafts, duplicates. Include files in whatever retention thinking covers your records, or storage becomes a surprise.

Test with an awkward file

A name with spaces and an accent, no extension, and a type your scope should refuse. Those three cover most upload behaviour, and they take a minute.

Worked example

An organisation restricts each upload field with a file scope, keeps everything on the private path except its public asset store, and forces simple names. A test with an unnamed, extensionless file confirmed it was refused rather than stored under a generated name nobody could find.

Recommendations

Use file scopes per field, not one global rule.
Private path by default.
Force simple names.
Test with deliberately awkward files.

Missing Names and Extensions

Two settings decide whether files arriving without a name, or without an extension, are accepted.

Where to find it

Architect Panel → Configuration:

Site Settings — the File Uploads and Audio/Video Conversion groups

Files without extensions

Allowed by default. Plenty of legitimate files have no extension — anything produced on a system that does not use them, files renamed in transit, and some exports.

The cost is that neither the platform nor the user’s device can tell what the file is from its name, so it downloads as something nobody can open.

Files without names

Refused by default, and that default is right. A file arriving with no name at all is nearly always a fault — a broken form, a misbehaving integration, or something deliberate.

Accepting them means storing files under generated names that nobody can identify afterwards.

Neither is a security control

The important caution. An extension tells you what a file claims to be, not what it is. A document renamed to end in an image extension is still a document, and one that is genuinely dangerous is not made safe by its name.

File scopes, storage location and how a file is served back are the controls. These two settings are about usability.

Decide by what your users send

If your uploads come from an integration producing extensionless files, allow them. If they come from people using ordinary devices, requiring an extension catches mistakes early and produces files that open when downloaded.

A refusal must be explained

Whichever way you set them, the message when a file is rejected should say what was wrong and what to do. "Upload failed" produces a support call; "this file has no name — please rename it and try again" does not.

Watch the error log

A sudden run of rejected uploads usually means an integration has changed rather than that users have. The log is where that shows.

Consider the download experience

A stored file with no extension is one somebody downloads and cannot open. If you accept them, consider whether the platform can supply a sensible name on download instead.

Test both

Upload a file with no extension and one with no name, and see what happens. That is a two-minute check on behaviour that is otherwise only discovered by a user.

Worked example

An organisation allows extensionless files because a supplier integration produces them, and refuses nameless ones. The rejection message names the problem. A run of failures in the error log identified a form change on the supplier’s side within a day.

Recommendations

Refuse nameless files — they are nearly always a fault.
Do not treat extensions as security.
Explain every refusal in the message.
Watch the log for a run of rejections.

Spaces in Filenames

One setting decides whether spaces in uploaded filenames are replaced with underscores.

Where to find it

Architect Panel → Configuration:

Site Settings — the File Uploads and Audio/Video Conversion groups

Where spaces cause trouble

In addresses — a space has to be encoded, and a filename appearing in a link is a filename that will be encoded inconsistently somewhere.
In command-line handling — anything processing files outside the platform.
In copied links — a pasted address containing an encoded space breaks in messages and documents.
Across systems — export, import, synchronisation, backup.

Where they do not

In the platform itself, where a stored filename is handled properly. If files are only ever uploaded, listed and downloaded through the interface, spaces are harmless.

Decide by what happens to the files

Files that stay inside the platform can keep their names as the user typed them, which is friendlier. Files that leave — into a share, an integration, a link somebody pastes into an e-mail — are better without spaces.

Consistency matters more than the choice

Either setting is defensible. What causes problems is changing it midway, so half your files have spaces and half do not, and anything matching filenames has to handle both.

Set it before there are files

Because it applies on upload. Existing files keep the names they were given, so a change produces a split library rather than a converted one.

It is not the same as safe names

The separate safe-name setting handles the genuinely problematic characters — accents, symbols, control characters, path separators. Spaces are a usability question; those are a correctness one.

Turn safe names on regardless of what you do about spaces.

Users notice

Somebody who uploads "Annual Report 2026.pdf" and downloads "Annual_Report_2026.pdf" will ask why. It is a small thing and worth a line of explanation next to the upload field if you have set it.

Worked example

An organisation replaces spaces because its files are synchronised to a shared drive and referenced in generated documents. It set this at installation, so the whole library is consistent, and the upload field says filenames will be simplified.

Recommendations

Replace spaces if files leave the platform.
Set it before there are files — it is not retrospective.
Turn safe names on regardless.
Tell users if names will change.

Safe Filenames

The safe-name setting reduces uploaded filenames to characters that behave predictably everywhere. It is on by default and should stay on.

Where to find it

Architect Panel → Configuration:

Site Settings — the File Uploads and Audio/Video Conversion groups

What arrives in a filename

Whatever the user’s device allowed. Accented characters, non-Latin scripts, emoji, quotation marks, semicolons, path separators, and occasionally control characters.

All of these are legitimate on somebody’s machine and several of them are a problem on yours.

Why it matters beyond tidiness

Path separators in a name are an attempt, deliberate or accidental, to write outside the intended directory.
Control characters can truncate or disguise what a name appears to be.
Names designed to look like something else — a long name whose visible portion suggests a different type.

Simplifying the name removes a class of problem rather than mitigating it.

It is not a substitute for the rest

A safe filename does not make a file safe. What matters equally is where it is stored, whether it can be executed, and how it is served back.

Private storage served through the platform, so permissions apply, is the control that does the heavy lifting.

Keep the original name somewhere

Users recognise their own filenames. Where the stored name is simplified, showing the original in the interface and using it on download keeps the file recognisable without storing it unsafely.

Watch out for collisions

Simplification can turn two different names into the same one. Confirm what happens when it does — a file silently replacing another is a data loss that nobody reports.

Test with a genuinely hostile name

Something containing a path separator, a quotation mark and a non-Latin script. Confirm it is stored under a name you are comfortable with and that it downloads correctly.

Do not turn it off for convenience

The usual reason is that somebody wants exact filenames preserved for an integration. Solve that by keeping the original name as data rather than by storing it as the actual name.

Worked example

An organisation keeps safe names on and stores the user’s original filename alongside, displaying it in the interface and using it on download. A test upload containing a path separator was stored under a simplified name, which is what the setting is for.

Recommendations

Leave it on, always.
Keep the original name as data, not as the stored name.
Check what happens on a collision.
Remember storage and serving matter more.

Large Uploads

Large files are not uploaded in one request. The browser splits them into chunks, the server reassembles them, and the whole transfer is tracked as an upload session you can inspect. On S3 installations a second route lets the browser send large files straight to the bucket instead. This article covers both, and how to diagnose an upload that will not finish.

Where to find it

Architect Panel → Data:

Large Uploads — upload sessions in progress and recently finished

Architect Panel → Automation:

Tasks — the Upload Housekeeping task that clears expired sessions

Architect Panel → Activity:

Error Log — why a session failed, and storage errors

The limits

Ordinary uploads through a File Upload field are sent in one request, up to the web server's limit (64 MB on a standard installation).
Chunked uploads are sent in 5 MB parts, up to 1 GB per file.
Direct uploads to S3 skip the server entirely, up to the same 1 GB unless your hosting administrator raises it. See Direct Uploads to S3.

All three limits, and whether direct uploads are on, are set by your hosting administrator. None is on a screen.

What a session records

Each row in Large Uploads records the upload key and the person who started it; the file name, extension, type and declared size against how much has been received; the chunk size and how many chunks are expected and received; where the file is going (datastore, field, record and storage kind); its state, the resulting file and any error; and when it started, when the last chunk arrived, and when it completed or expires.

Three fields describe how the file arrived: Transport is "chunked" when the parts came through the server and "direct" when the browser sent the file straight to S3. Staged Object and Staged ETag are used by direct uploads only. A Staged Object still filled in after a direct upload completed means the temporary copy could not be deleted, so the file is briefly stored twice; housekeeping retries the delete.

Each chunk is recorded

Chunks record their number, size, a checksum, where they were staged and when they arrived. A session that is missing chunks cannot be finalised, so a broken connection produces an incomplete session, never a silently truncated file.

Sessions expire, and housekeeping clears them

A session that is not finished within 24 hours expires. Expiry stops it being resumed, but its staged parts are only removed when the Upload Housekeeping task runs. That task ships switched off and in preview mode, so on a new installation abandoned uploads accumulate until you turn it on:

Open Tasks and find Upload Housekeeping. It runs hourly once enabled.
Use its Preview row action. Preview describes what the task would clear and changes nothing.
Enable it and switch preview mode off on the task's row. The Task Log row action then shows each run.

Diagnosing a failing upload

Ask for the file name and roughly when they tried.
Find the session in Large Uploads. Compare the received size with the declared size, and note when the last chunk arrived.
Read the error on the session, then the Error Log at the same time.
If several people stall at a similar point, look for a size limit somewhere in the path, such as a proxy or load balancer, rather than at the platform.

What goes wrong

A large file fails and no session appears in Large Uploads. The file went as an ordinary single request and hit the web server's limit, or a proxy in front of the server refused it first.
Staging storage fills up. Upload Housekeeping is not enabled.
On Azure, a large upload reaches 100% and then fails. The chunks arrived; the server's transfer to Azure failed. The Error Log has the Azure error.

Worked example

A team investigating failed video uploads finds sessions stalling at the same received size, which points to a proxy limit rather than the platform; the proxy is fixed. Looking at Large Uploads, they also notice hundreds of expired sessions from the past year. Upload Housekeeping had never been enabled. Its Preview lists them, and once it is enabled the staged parts are cleared within the hour.

Recommendations

Enable Upload Housekeeping after checking its preview.
Use the session to diagnose, not the user's account.
A common stall size means a limit in the path.
Test from a phone on mobile data, and interrupt the upload part way.

Direct Uploads to S3

Direct uploads let the browser send a large file straight to your S3 bucket instead of passing it through the web server. The server signs a one-off permission for that exact file, the browser posts the file to a holding area in the bucket, and the server then checks it and moves it into place. Use it on S3 installations where people upload large files, so those files stop tying up the server's disk and bandwidth.

Where to find it

Architect Panel → Data:

Large Uploads — each upload session, with Transport showing "direct" or "chunked"

Architect Panel → Automation:

Tasks — Upload Housekeeping, which also retries clean-up after direct uploads

Architect Panel → Integration & Connections:

Deployments — the File Storage card, to confirm the installation is on Amazon S3

The switch itself and the bucket rules are set by your hosting administrator. There is no screen setting.

When it is used

Direct uploads only happen when all of these are true:

The installation's storage backend is Amazon S3. Local and Azure installations always use the chunked route.
Your hosting administrator has switched direct uploads on. It ships off.
The file is at least 8 MB. Below that, posting it to the server is quicker.
The upload comes from a File Upload field on a record, or from a record's documents pane.

Even then, the platform quietly uses the chunked route instead for files it needs to handle on the server: images (which are resized), Web Video fields, files going into a File Store, fields with a custom file processor, and every file when antivirus scanning with ClamAV is switched on. People see no difference either way.

What your hosting administrator sets up

A CORS rule on the bucket allowing POST from your site's address (and any custom tenant domains). Without it, browsers refuse to send the file.
A lifecycle rule that expires the holding area (the _amincoming/ prefix) after a day, so files abandoned mid-upload do not accumulate. Expiring incomplete multipart uploads is also sensible.
The direct upload switch, and if wanted a higher maximum file size than the standard 1 GB. Direct uploads can handle up to 4 GB per file.

What is checked

The permission the browser receives is for one exact file name, one exact size and one content type chosen by the server, and it lasts only as long as the file needs to upload, up to six hours. When the upload finishes, the server checks the stored size matches exactly, reads the start of the file to confirm its real type, moves it to its proper place and deletes the holding copy. A file that fails a check never becomes a file in the platform. The same file-type rules apply as for any other upload.

Checking it works

Confirm with your hosting administrator that the bucket rules are in place before the switch is turned on.
Upload a non-image file over 8 MB, such as a large PDF or ZIP, to a File Upload field.
Open Large Uploads and find the session. Transport should read "direct", and Staged Object should be empty once it completes.
Download the file and confirm it opens.

What goes wrong

Transport always reads "chunked". Direct uploads are off, the file is under 8 MB, or it is one of the kinds that always takes the chunked route. Check with an ordinary large PDF.
The upload falls back after a pause. If the browser's post to S3 fails, usually because of a missing CORS rule, the upload is abandoned and retried once through the server. It still succeeds, but slowly; ask for the CORS rule to be checked.
Staged Object stays filled in on completed sessions. The holding copy could not be deleted, so the file is stored twice. Upload Housekeeping retries the delete, so make sure it is enabled.
The Error Log says the server fell back to the chunked transport. The server could not sign the upload, often because of an S3 credential problem.

Worked example

An engineering firm's surveyors attach 300 MB drawing archives to site records. On chunked uploads each one passed through the server twice, and three at once slowed the site for everybody. The hosting administrator adds the CORS and lifecycle rules and turns direct uploads on. The next archive's session shows Transport "direct" with an empty Staged Object, and the server's load during uploads drops away. Photos are still resized on the server, as before.

Recommendations

Put the bucket rules in place first, then turn the switch on.
Enable Upload Housekeeping so leftover holding copies are cleared.
Test with a large non-image file, because images always go through the server.
Use Large Uploads to confirm which route each file actually took.