KB-2423 Document upload fails with FileSystemException when using Azure files in Appian on Kubernetes

Symptoms

• All users cannot upload documents to most Knowledge Centers in Appian on Kubernetes deployed on Azure.
• Document uploads to certain Knowledge Centers may succeed, particularly the first Knowledge Center created in the environment.
• This error message is displayed to users: Action Failed - The document could not be created. You may have lost permissions to the parent folder.
• The tomcat-stdOut.log file inside the Webapp Pod shows the following error messages:

  com.appiancorp.process.runtime.forms.components.InlineFileUpload - Could not deactivate or make transient document with id [ID]
  
  com.appiancorp.suiteapi.content.exceptions.InvalidContentException: Invalid Content ID
  
  com.appiancorp.process.runtime.forms.components.InlineFileUpload - Could not move file to new location with id [ID]
  
  java.nio.file.FileSystemException: /usr/local/appian/ae/_admin/accdocsX/[folder]/[file].csv: Operation not permitted

   

• If enabled, DEBUG logs show Appian attempting a non-atomic move operation between accdocs directories (e.g., from accdocsX/XXXX to accdocsY/XXXX) and failing with a FileSystemException.

Cause

The root cause is missing the noperm mount option on the Azure Files share used by the Webapp PV.

When Azure Files is mounted via the CIFS/SMB protocol in Kubernetes, file move operations across mount points require the noperm option to bypass Linux permission checks that are incompatible with Azure Files' permission model. Without this option, cross-mount file operations (such as moving uploaded documents from transient storage to their final Knowledge Center location) fail with "Operation not permitted" errors, even though the underlying filesystem has correct read/write permissions.

Action

1. Identify the PV name for the Webapp: kubectl -n <NAMESPACE> get pv
   If you have haExistingClaim configured in your environment, this is the PV in question: kubectl -n <NAMESPACE> get pv
2. Edit the identified PV: kubectl edit pv <PV-NAME>
3. Under the spec section, add a mountOptions section if it does not exist, then add noperm under mountOptions.
4. Save and exit the editor.
5. Restart the Webapp Pod to apply the new mount options: kubectl -n <NAMESPACE> delete pod <WEBAPP-POD-NAME>
6. Verify the mount options are applied: kubectl -n <NAMESPACE> exec -it <WEBAPP-POD-NAME> -- bash and run mount | grep accdocs (The output should include noperm in the mount options).
7. Test document upload functionality by uploading a document to a Knowledge Center that previously failed.

If there is a storage class configured in the Kubernetes cluster, the storage class should also be modified to include the noperm mount option. This ensures any future PVs are created with this mount option.

1. Identify the storage class: kubectl get sc
2. Edit the storage class: kubectl edit sc <SC-NAME>
3. Add a mountOptions section if it does not exist, then add noperm under mountOptions.
4. Save and exit the editor.

Affected Versions

This article applies to all self-managed versions of Appian on Kubernetes running on Azure.

Last Reviewed: October 2026