Folder encoding issue on Linux App Service using AzureRmWebAppDeployment/KuduSync

Question

Folder encoding issue on Linux App Service using AzureRmWebAppDeployment/KuduSync

Danny Fournier 0

Our pipeline introduces, for a reason unknown to us, a folder encoding issue in our Linux App Service during deployment.

Once our app is deployed, a folder "méli-mélo" will get deployed as 'm'$'\351''li-m'$'\351''lo'.

ls -la
d????????? ? ? ? ? ? 'm'$'\351''li-m'$'\351''lo'

No issues from the DevOps Repository
No issues from our local environments (VSCode/Docker, PHP 8.2 FPM, Debian Slim?)
No issues from the artifact (downloaded and extracted in our Docker local environment)

Log showing the usage of KuduSync:

[
  {
    "log_time": "2025-06-16T15:35:24.2887097Z",
    "id": "",
    "message": "Command: \"/home/site/deployments/tools/deploy.sh\"",
    "type": 0,
    "details_url": null
  },
  {
    "log_time": "2025-06-16T15:35:24.3349317Z",
    "id": "",
    "message": "Handling Basic Web Site deployment.",
    "type": 0,
    "details_url": null
  },
  {
    "log_time": "2025-06-16T15:35:24.4060169Z",
    "id": "",
    "message": "Kudu sync from: '/tmp/zipdeploy/extracted' to: '/home/site/wwwroot'",
    "type": 0,
    "details_url": null
  },
  ...
  {
    "log_time": "2025-06-16T15:46:51.4061573Z",
    "id": "",
    "message": "Processed 11852 files...",
    "type": 0,
    "details_url": null
  },
  {
    "log_time": "2025-06-16T15:46:58.5474741Z",
    "id": "",
    "message": "Finished successfully.",
    "type": 0,
    "details_url": null
  }
]

Pipeline YAML that uses AzureRmWebAppDeployment@5 (KuduSync?) to deploy

trigger:
- master
variables:
  # Azure Resource Manager connection created during pipeline creation
  azureSubscription: 'our_sub'
  azureResourceGroup: 'our_rg'
  azureSelfHostedAgent: 'our-win2019-agent'
  # Web app name
  webAppName: 'our-app-service'
  # Agent VM image name
  vmImageName: 'ubuntu-24.04'
  # Environment name
  environmentName: 'our-app-service'
  # Root folder under which your composer.json file is available.
  rootFolder: $(System.DefaultWorkingDirectory)
stages:
- stage: Build
  displayName: Build stage
  variables:
    phpVersion: '8.2'
  jobs:
  - job: Buildjob
    pool:
      vmImage: $(vmImageName)
    steps:
    - bash: |
        echo "##vso[task.setvariable variable=short_hash]${BUILD_SOURCEVERSION:0:8}"
    - bash: |
        echo "##vso[task.setvariable variable=long_hash]${BUILD_SOURCEVERSION}"
    - script: |        
        sudo update-alternatives --set php /usr/bin/php$(phpVersion)       
        sudo update-alternatives --set phar /usr/bin/phar$(phpVersion)
        sudo update-alternatives --set phpdbg /usr/bin/phpdbg$(phpVersion)
        sudo update-alternatives --set php-cgi /usr/bin/php-cgi$(phpVersion)
        sudo update-alternatives --set phar.phar /usr/bin/phar.phar$(phpVersion)  
        php -version
      workingDirectory: $(rootFolder)
      displayName: 'Use PHP version $(phpVersion)'
    - script: composer install --no-interaction --prefer-dist
      workingDirectory: $(rootFolder)
      displayName: 'Composer install'
    
    - script: |       
        cp config/app_local.azure.php config/app_local.php
        sed -i 's/__SALT__/$(__SALT__)/g' config/app_local.php
        sed -i 's/__HOST__/$(__HOST__)/g' config/app_local.php	
        sed -i 's/__USER__/$(__USER__)/g' config/app_local.php
        sed -i 's/__PASSWORD__/$(__PASSWORD__)/g' config/app_local.php
        sed -i 's/__DB__/$(__DB__)/g' config/app_local.php
        sed -i 's/__DEBUG__/false/g' config/app_local.php
        sed -i 's,__FULLBASEURL__,$(__FULLBASEURL__),g' config/app_local.php
        sed -i 's/__ENVIRONMENT__/$(__ENVIRONMENT__)/g' config/app_local.php
        sed -i 's/__SHORTGITCOMMIT__/$(short_hash)/g' config/app_local.php
        sed -i 's/__LONGGITCOMMIT__/$(long_hash)/g' config/app_local.php
        sed -i 's/__SDI_DB__/$(__SDI_DB__)/g' config/app_local.php
        rm -f composer.json
        rm -f composer.lock
        rm -rf .git
      workingDirectory: $(rootFolder)
      displayName: 'PreBuild'
    - task: ArchiveFiles@2
      displayName: 'Archive files'
      inputs:
        rootFolderOrFile: '$(rootFolder)'
        includeRootFolder: false
        archiveType: zip
        archiveFile: $(Build.ArtifactStagingDirectory)/$(Build.BuildId).zip
        replaceExistingArchive: true
    
    - task: CopyFiles@2
      inputs:
        Contents: '*.ps1'
        TargetFolder: '$(Build.ArtifactStagingDirectory)'
    - publish: $(Build.ArtifactStagingDirectory)
      displayName: 'Upload package'
      artifact: drop
  
  - job: DeployJob
    pool: '$(azureSelfHostedAgent)'
    workspace:
      clean: all
    steps:
    - checkout: none
    - task: DownloadPipelineArtifact@2
      inputs:
        artifact: drop
        path: $(System.DefaultWorkingDirectory)
    - task: AzurePowerShell@5
      displayName: 'Clean Azure App Service'
      inputs:
        azureSubscription: '$(azureSubscription)'
        ScriptPath: '$(System.DefaultWorkingDirectory)/SandBoxCleanup.ps1'
        azurePowerShellVersion: LatestVersion
        pwsh: true
        workingDirectory: '$(System.DefaultWorkingDirectory)'
    - task: AzureRmWebAppDeployment@5
      displayName: 'Deploy Azure App Service'
      inputs:
        azureSubscription: '$(azureSubscription)'
        appType: '$(WebAppKind)'
        WebAppName: '$(WebAppName)'
        ResourceGroupName: '$(azureResourceGroup)'
        packageForLinux: '$(System.DefaultWorkingDirectory)/*.zip'
        CleanDeploymentFlag: true
        RemoveAdditionalFilesFlag: true
        DeploymentTypeLinux: 'oneDeploy'
    
    dependsOn: BuildJob

Siva Nair 2,340 Reputation points Microsoft External Staff Moderator

2025-06-16T18:33:25.81+00:00
Hi Danny Fournier,

Reaching you out in private chat for more details , please check.

The fact that the folder "méli-mélo" ends up as 'm'$'\351''li-m'$'\351''lo' suggests that there's a character encoding mismatch happening during the deployment process.

Here are a few things you can consider to help resolve this:

Make sure that your local environment (where you're preparing the deployment) uses the same character encoding as the Azure environment. Ensure you're using UTF-8 or the encoding that best fits your needs.

When creating your ZIP package for deployment, ensure that the tools you're using to create the ZIP file correctly preserve the folder names and their encodings. Sometimes, using different compression tools can lead to different behaviors.

Since you mentioned that you're using AzureRmWebAppDeployment which utilizes KuduSync, ensure that there aren't any steps where the encoding could be altered. If possible, consider using direct FTP or Kudu ZIP deployment to see if that changes the outcome.

KuduSync should maintain the file metadata, but there could be underlying issues with character support in the deployment process. Check if there are any options or parameters in your pipeline setup that could enforce stricter encoding handling.

As a troubleshooting step, try deploying a different package with similar folder names (but with altered encoding) to see if it behaves the same way. This can help isolate whether the issue is with KuduSync or how the folder names are generated/prepared for deployment.

If you have any further assistant, do let me know.
Gaurav Kumar 780 Reputation points Microsoft External Staff Moderator

2025-06-17T05:35:38.1666667+00:00

Hi @Danny Fournier ,

Just checking in to see if above information was helpful. If you have any further updates on this issue, please feel free to post back.
Danny Fournier 0 Reputation points

2025-06-17T11:23:09.2966667+00:00

Can I get more details on the Kudu ZIP deployment process? The basics on how that would work?

The pipeline, code above, uses available tasks and modules. Unsure how they could be configured to circumvent this issue.

FWIW, all our apps (7) are configured the same way and reuse a lot of base templates (pipelines, pipeline yaml, release pipelines, PHP framework, etc.). However, it seems to be random in terms of the issue cropping up. Some apps don't have any issues, some it's the SBX environment, others is DEV, from the same codebase/commits.
Sampath 3,750 Reputation points Microsoft External Staff Moderator

2025-06-17T11:53:45.6566667+00:00

Hi @Danny Fournier , Refer this MSDOC for Deploy with ZIP deploy UI in Kudu
Bodapati Harish 820 Reputation points Microsoft External Staff Moderator

2025-06-17T12:22:08.5266667+00:00
Hi Danny Fournier,

Thanks for the follow-up. Since the issue does not occur in your source code, artifact, or local environment and only appears after deployment, it points to how the deployment package is being extracted and interpreted inside the App Service environment. The corrupted folder name is a result of UTF-8 characters being misinterpreted during ZIP extraction on Linux-based App Services.

Even though all your apps and pipelines are using the same templates, the behavior varies across environments (like SBX, DEV, etc.) because Linux App Services do not always enforce UTF-8 by default. Some environments may have the correct locale settings, while others may not, which explains the randomness you're observing despite the same code and pipeline structure.

Your current setup uses the ArchiveFiles@2 task to create the ZIP and AzureRmWebAppDeployment@5 with DeploymentTypeLinux set to oneDeploy. This combination works for basic deployments but does not guarantee reliable handling of special characters in folder or file names, especially when the App Service is not explicitly configured for UTF-8.

To fix this issue consistently across all environments, you can make the following changes:

Use the zip CLI to create the archive with UTF-8 encoding

Replace the ArchiveFiles@2 task with a script that uses the native zip command. This ensures that folder names are encoded using UTF-8 and preserved correctly when extracted.

- script: | sudo apt-get update && sudo apt-get install zip -y zip -r --quiet --unicode UTF8 $(Build.ArtifactStagingDirectory)/build.zip . workingDirectory: $(rootFolder) displayName: 'Create UTF-8 encoded zip archive'

Switch the deployment method to zipDeploy

Update your deployment step to use DeploymentTypeLinux: 'zipDeploy'. This method uploads the ZIP archive directly to the Kudu ZIP deployment endpoint and extracts it in one operation. It avoids file-by-file syncing, which is more sensitive to character encoding inconsistencies.

DeploymentTypeLinux: 'zipDeploy'

Configure the App Service environment to use UTF-8

In the Azure Portal, go to your App Service > Configuration > Application Settings, and add the following entries:

LANG = en_US.UTF-8 LC_ALL = en_US.UTF-8

These settings ensure that the Linux container extracts and runs your app using the correct encoding for folder and file names.

By applying these three updates UTF-8-compliant ZIP creation, zipDeploy for deployment, and proper environment configuration you’ll eliminate the folder name corruption issue across all environments and apps.

References

Kudu ZIP Deploy – Azure App Service

AzureRmWebAppDeployment – Azure Pipelines
Danny Fournier 0 Reputation points

2025-06-17T13:11:32.7066667+00:00

Configuring UTF-8 for the app services, you mean going into the Environment Variables? This is the only spot I can see where I can add these.
Sampath 3,750 Reputation points Microsoft External Staff Moderator

2025-06-17T13:27:31.73+00:00
Hi Danny Fournier,
You add like below in azure app.

You’ll need to add LANG and LC_ALL as environment variables in your App Service using the Azure Portal.

Here’s how to do it:

Go to Azure Portal > App Services > select your app > Configuration (under the Settings section) > Application settings tab.

Click on + New application setting, then enter:

- Name: LANG - Value: en_US.UTF-8

Click OK, then add another setting:

- Name: LC_ALL - Value: en_US.UTF-8

After adding both, click Save at the top. Azure will prompt you to restart the app — confirm the restart so the new settings take effect.

These settings ensure that your App Service uses UTF-8 encoding at runtime, which allows special characters in folder names to be handled correctly during deployment.
(or)

Run the following command in Azure Cloud Shell:

az webapp config appsettings set --resource-group <group-name> --name <app-name> --settings SCM_DO_BUILD_DURING_DEPLOYMENT=true

For more information, see Kudu documentation.

Danny Fournier 0

Following these changes (and a restart), when I SSH into the app service, I get:

-bash: warning: setlocale: LC_ALL: cannot change locale (en_US.UTF-8)

Output of locale command:

root@d3a9f59bcd1f:/home# locale
LANG=en_US.UTF-8
LANGUAGE=C.UTF-8
LC_CTYPE="C.UTF-8"
LC_NUMERIC="C.UTF-8"
LC_TIME="C.UTF-8"
LC_COLLATE="C.UTF-8"
LC_MONETARY="C.UTF-8"
LC_MESSAGES="C.UTF-8"
LC_PAPER="C.UTF-8"
LC_NAME="C.UTF-8"
LC_ADDRESS="C.UTF-8"
LC_TELEPHONE="C.UTF-8"
LC_MEASUREMENT="C.UTF-8"
LC_IDENTIFICATION="C.UTF-8"
LC_ALL=C.UTF-8

Bodapati Harish 820 Microsoft External Staff Moderator

Hi Danny Fournier,

Great job getting those settings applied. The warning you're seeing:

-bash: warning: setlocale: LC_ALL: cannot change locale (en_US.UTF-8)

just means that the Linux container doesn’t have the full en_US.UTF-8 locale installed. That’s normal on App Service for Linux and nothing to worry about.

As a fallback, the system uses C.UTF-8, which still fully supports UTF-8 encoding. From your locale output, we can see that UTF-8 is active through C.UTF-8, so it will still handle special characters like é correctly in folder names. You can now continue with a test deployment using the updated pipeline and zipDeploy`.

Please try with the modified YAML file below. It includes the necessary changes to resolve the folder encoding issue on Linux App Service.


trigger:

- master

variables:

  azureSubscription: 'our_sub'

  azureResourceGroup: 'our_rg'

  azureSelfHostedAgent: 'our-win2019-agent'

  webAppName: 'our-app-service'

  vmImageName: 'ubuntu-24.04'

  environmentName: 'our-app-service'

  rootFolder: $(System.DefaultWorkingDirectory)

stages:

- stage: Build

  displayName: Build stage

  variables:

    phpVersion: '8.2'

  jobs:

  - job: Buildjob

    pool:

      vmImage: $(vmImageName)

    steps:

    - bash: |

        echo "##vso[task.setvariable variable=short_hash]${BUILD_SOURCEVERSION:0:8}"

    - bash: |

        echo "##vso[task.setvariable variable=long_hash]${BUILD_SOURCEVERSION}"

    - script: |        

        sudo update-alternatives --set php /usr/bin/php$(phpVersion)       

        sudo update-alternatives --set phar /usr/bin/phar$(phpVersion)

        sudo update-alternatives --set phpdbg /usr/bin/phpdbg$(phpVersion)

        sudo update-alternatives --set php-cgi /usr/bin/php-cgi$(phpVersion)

        sudo update-alternatives --set phar.phar /usr/bin/phar.phar$(phpVersion)  

        php -version

      workingDirectory: $(rootFolder)

      displayName: 'Use PHP version $(phpVersion)'

    - script: composer install --no-interaction --prefer-dist

      workingDirectory: $(rootFolder)

      displayName: 'Composer install'

    - script: |       

        cp config/app_local.azure.php config/app_local.php

        sed -i 's/__SALT__/$(__SALT__)/g' config/app_local.php

        sed -i 's/__HOST__/$(__HOST__)/g' config/app_local.php	

        sed -i 's/__USER__/$(__USER__)/g' config/app_local.php

        sed -i 's/__PASSWORD__/$(__PASSWORD__)/g' config/app_local.php

        sed -i 's/__DB__/$(__DB__)/g' config/app_local.php

        sed -i 's/__DEBUG__/false/g' config/app_local.php

        sed -i 's,__FULLBASEURL__,$(__FULLBASEURL__),g' config/app_local.php

        sed -i 's/__ENVIRONMENT__/$(__ENVIRONMENT__)/g' config/app_local.php

        sed -i 's/__SHORTGITCOMMIT__/$(short_hash)/g' config/app_local.php

        sed -i 's/__LONGGITCOMMIT__/$(long_hash)/g' config/app_local.php

        sed -i 's/__SDI_DB__/$(__SDI_DB__)/g' config/app_local.php

        rm -f composer.json

        rm -f composer.lock

        rm -rf .git

      workingDirectory: $(rootFolder)

      displayName: 'PreBuild'

    # Replaced ArchiveFiles@2 with zip CLI to preserve UTF-8 encoding

    - script: |

        sudo apt-get update && sudo apt-get install zip -y

        zip -r --quiet --unicode UTF8 $(Build.ArtifactStagingDirectory)/$(Build.BuildId).zip .

      workingDirectory: $(rootFolder)

      displayName: 'Create UTF-8 encoded ZIP archive'

    - task: CopyFiles@2

      inputs:

        Contents: '*.ps1'

        TargetFolder: '$(Build.ArtifactStagingDirectory)'

    - publish: $(Build.ArtifactStagingDirectory)

      displayName: 'Upload package'

      artifact: drop

- stage: Deploy

  displayName: Deploy stage

  jobs:

  - job: DeployJob

    pool: '$(azureSelfHostedAgent)'

    workspace:

      clean: all

    steps:

    - checkout: none

    - task: DownloadPipelineArtifact@2

      inputs:

        artifact: drop

        path: $(System.DefaultWorkingDirectory)

    - task: AzurePowerShell@5

      displayName: 'Clean Azure App Service'

      inputs:

        azureSubscription: '$(azureSubscription)'

        ScriptPath: '$(System.DefaultWorkingDirectory)/SandBoxCleanup.ps1'

        azurePowerShellVersion: LatestVersion

        pwsh: true

        workingDirectory: '$(System.DefaultWorkingDirectory)'

    - task: AzureRmWebAppDeployment@5

      displayName: 'Deploy Azure App Service'

      inputs:

        azureSubscription: '$(azureSubscription)'

        appType: '$(WebAppKind)'

        WebAppName: '$(WebAppName)'

        ResourceGroupName: '$(azureResourceGroup)'

        packageForLinux: '$(System.DefaultWorkingDirectory)/*.zip'

        CleanDeploymentFlag: true

        RemoveAdditionalFilesFlag: true

        DeploymentTypeLinux: 'zipDeploy'

    dependsOn: BuildJob

Danny Fournier 0

Still get the encoded issue

Quick Recap:

Deleted and recreated our app service
Added environment variable LANG=en_US.UTF-8 and restarted
Changed to pipeline yaml to zipDeploy
Changed the zipping process

Azure App Service deploy log:

Starting: Deploy Azure App Service
==============================================================================
Task         : Azure App Service deploy
Description  : Deploy to Azure App Service a web, mobile, or API app using Docker, Java, .NET, .NET Core, Node.js, PHP, Python, or Ruby
Version      : 5.257.0
Author       : Microsoft Corporation
Help         : https://aka.ms/azureappservicetroubleshooting
==============================================================================
Got service connection details for Azure App Service:'my-app-service'
Package deployment using ZIP Deploy initiated.
Deploy logs can be viewed at https://my-app-service.scm.xxx.appserviceenvironment.net/api/deployments/ab44b5f0-a287-4fba-bfe2-d8fe47f69c83/log
Successfully deployed web package to App Service.
Successfully updated App Service configuration details
Successfully updated deployment History at https://my-app-service.scm.xxx.appserviceenvironment.net/api/deployments/52141750173911357
App Service Application URL: https://my-app-service.xxx.appserviceenvironment.net
Finishing: Deploy Azure App Service

From the various logs:

{
	"log_time": "2025-06-17T15:13:29.117118Z",
	"id": "",
	"message": "Using the following command to generate deployment script: 'azure site deploymentscript -y --no-dot-deployment -r \"/tmp/zipdeploy/extracted\" -o \"/home/site/deployments/tools\" --basic --sitePath \"/tmp/zipdeploy/extracted\"'.",
	"type": 0,
	"details_url": null
},
...
{
	"log_time": "2025-06-17T15:13:29.6861588Z",
	"id": "",
	"message": "Kudu sync from: '/tmp/zipdeploy/extracted' to: '/home/site/wwwroot'",
	"type": 0,
	"details_url": null
},
...
{
	"log_time": "2025-06-17T15:24:23.5456004Z",
	"id": "",
	"message": "Finished successfully.",
	"type": 0,
	"details_url": null
}

Pipeline YAML:

# PHP as Linux Web App on Azure
# Build, package and deploy your PHP project to Azure Linux Web App.
# Add steps that run tests and more:
# https://docs.microsoft.com/azure/devops/pipelines/languages/php
trigger:
- master
variables:
  # Azure Resource Manager connection created during pipeline creation
  azureSubscription: 'our-sub'
  azureResourceGroup: 'our-rg'
  azureSelfHostedAgent: 'our-agent'
  # Web app name
  webAppName: 'our-app-service'
  # Agent VM image name
  vmImageName: 'ubuntu-24.04'
  # Environment name
  environmentName: 'our-app-service'
  # Root folder under which your composer.json file is available.
  rootFolder: $(System.DefaultWorkingDirectory)
stages:
- stage: Build
  displayName: Build stage
  variables:
    phpVersion: '8.2'
  jobs:
  - job: Buildjob
    pool:
      vmImage: $(vmImageName)
    steps:
    - bash: |
        echo "##vso[task.setvariable variable=short_hash]${BUILD_SOURCEVERSION:0:8}"
    - bash: |
        echo "##vso[task.setvariable variable=long_hash]${BUILD_SOURCEVERSION}"
    - script: |        
        sudo update-alternatives --set php /usr/bin/php$(phpVersion)       
        sudo update-alternatives --set phar /usr/bin/phar$(phpVersion)
        sudo update-alternatives --set phpdbg /usr/bin/phpdbg$(phpVersion)
        sudo update-alternatives --set php-cgi /usr/bin/php-cgi$(phpVersion)
        sudo update-alternatives --set phar.phar /usr/bin/phar.phar$(phpVersion)  
        php -version
      workingDirectory: $(rootFolder)
      displayName: 'Use PHP version $(phpVersion)'
    - script: composer install --no-interaction --prefer-dist
      workingDirectory: $(rootFolder)
      displayName: 'Composer install'
    
    - script: |       
        cp config/app_local.azure.php config/app_local.php
        sed -i 's/__SALT__/$(__SALT__)/g' config/app_local.php
        sed -i 's/__HOST__/$(__HOST__)/g' config/app_local.php	
        sed -i 's/__USER__/$(__USER__)/g' config/app_local.php
        sed -i 's/__PASSWORD__/$(__PASSWORD__)/g' config/app_local.php
        sed -i 's/__DB__/$(__DB__)/g' config/app_local.php
        sed -i 's/__DEBUG__/false/g' config/app_local.php
        sed -i 's,__FULLBASEURL__,$(__FULLBASEURL__),g' config/app_local.php
        sed -i 's/__ENVIRONMENT__/$(__ENVIRONMENT__)/g' config/app_local.php
        sed -i 's/__SHORTGITCOMMIT__/$(short_hash)/g' config/app_local.php
        sed -i 's/__LONGGITCOMMIT__/$(long_hash)/g' config/app_local.php
        sed -i 's/__SDI_DB__/$(__SDI_DB__)/g' config/app_local.php
        rm -f composer.json
        rm -f composer.lock
        rm -rf .git
      workingDirectory: $(rootFolder)
      displayName: 'PreBuild'
    - script: |
        sudo apt-get update && sudo apt-get install zip -y
        zip -r --quiet --unicode UTF8 $(Build.ArtifactStagingDirectory)/$(Build.BuildId).zip .
      workingDirectory: $(rootFolder)
      displayName: 'Create UTF-8 encoded zip archive'
  
    # - task: ArchiveFiles@2
    #   displayName: 'Archive files'
    #   inputs:
    #     rootFolderOrFile: '$(rootFolder)'
    #     includeRootFolder: false
    #     archiveType: zip
    #     archiveFile: $(Build.ArtifactStagingDirectory)/$(Build.BuildId).zip
    #     replaceExistingArchive: true
    
    - task: CopyFiles@2
      inputs:
        Contents: '*.ps1'
        TargetFolder: '$(Build.ArtifactStagingDirectory)'
    - publish: $(Build.ArtifactStagingDirectory)
      displayName: 'Upload package'
      artifact: drop
  
  - job: DeployJob
    pool: '$(azureSelfHostedAgent)'
    workspace:
      clean: all
    steps:
    - checkout: none
    - task: DownloadPipelineArtifact@2
      inputs:
        artifact: drop
        path: $(System.DefaultWorkingDirectory)
    - task: AzurePowerShell@5
      displayName: 'Clean Azure App Service'
      inputs:
        azureSubscription: '$(azureSubscription)'
        ScriptPath: '$(System.DefaultWorkingDirectory)/SandBoxCleanup.ps1'
        azurePowerShellVersion: LatestVersion
        pwsh: true
        workingDirectory: '$(System.DefaultWorkingDirectory)'
    - task: AzureRmWebAppDeployment@5
      displayName: 'Deploy Azure App Service'
      inputs:
        azureSubscription: '$(azureSubscription)'
        appType: 'webAppLinux'
        WebAppName: '$(WebAppName)'
        ResourceGroupName: '$(azureResourceGroup)'
        packageForLinux: '$(System.DefaultWorkingDirectory)/*.zip'
        CleanDeploymentFlag: true
        RemoveAdditionalFilesFlag: true
        DeploymentTypeLinux: 'zipDeploy'
    dependsOn: BuildJob

Danny Fournier 0 Reputation points

2025-06-17T17:55:30.7066667+00:00

Noting that "our-agent" is Windows Server 2019 Data Center... perhaps this is where the issue lies? Ubuntu and the app Service have been confirmed as being UTF-8.
Bodapati Harish 820 Reputation points Microsoft External Staff Moderator

2025-06-18T08:59:35.3533333+00:00
Hi Danny Fournier,

Thanks for the thorough recap. Given that your App Service and the final extraction environment are confirmed to support UTF-8, the remaining culprit is where the ZIP archive is created your self-hosted Windows Server 2019 agent. Windows does not reliably embed filenames as UTF-8 in ZIP metadata, even when you use the zip command with Unicode flags. When that archive is unpacked on Linux, the special characters get misread and folders end up with escape sequences instead of proper names.

To solve this once and for all, move the build and ZIP creation step onto a Linux agent. Linux agents natively store filenames in UTF-8, so your “méli-mélo” folder will remain intact through to the App Service. You can leave the deploy job on Windows if you need to, but the archive must be built on Linux.

In your YAML, simply change the Buildjob pool like:

- job: Buildjob pool: vmImage: ubuntu-24.04

Keep all your existing steps, including the zip -r --unicode UTF8 call and the switch to zipDeploy. Once the ZIP is built on Linux, the App Service extract will preserve the correct folder names.
Danny Fournier 0 Reputation points

2025-06-18T10:48:05.4833333+00:00

Really appreciate the feedback!

I wanted to highlight that the job that produces the zip file (ie. BuildJob) already uses Ubuntu. The pool of the job uses the variable $(vmImageName) that has a value of "ubuntu-24.04".

It's the DeployJob that uses the pool "our-agent", which is Windows 2019, from the variable $(azureSelfHostedAgent).

Maybe we need to add a Linux self hosted agent?
Bodapati Harish 820 Reputation points Microsoft External Staff Moderator

2025-06-18T11:47:33.2333333+00:00
Hi Danny Fournier,

Since your build job already runs on Ubuntu and produces a proper UTF-8 ZIP, adding a Linux agent for the deploy job won’t help. The last step that mangles folder names is KuduSync copying files into wwwroot. To eliminate that, use Run-From-Package so the App Service mounts your ZIP directly instead of unpacking and syncing it.

You don’t need to change your build steps or agent pools. Just enable Run-From-Package and keep using zipDeploy:

Enable Run-From-Package in the Azure Portal

Azure Portal > App Services > select your app > Configuration (under Settings) > Application settings tab > + New application setting

Name: WEBSITE_RUN_FROM_PACKAGE

Value: 1

Click OK, then Save and agree to restart the app.

Or add this before deployment in your YAML

- task: AzureCLI@2 displayName: Enable Run-From-Package inputs: azureSubscription: '$(azureSubscription)' scriptType: bash scriptLocation: inlineScript inlineScript: | az webapp config appsettings set \ --name $(webAppName) \ --resource-group $(azureResourceGroup) \ --settings WEBSITE_RUN_FROM_PACKAGE=1

Leave your zipDeploy step as it is. Once Run-From-Package is on, special-character folders like “méli-mélo” will appear correctly, because the ZIP isn’t unpacked with KuduSync. Let me know how it goes
Danny Fournier 0 Reputation points

2025-06-18T12:33:50.76+00:00
Thanks for the reply. I was reading about WEBSITE_RUN_FROM_PACKAGE and found this:

When you run from a package, the wwwroot folder is read-only and you receive an error if you write files to this directory. Files are also read-only in the Azure portal.

This is a stopper for us as we're writing files in wwwroot.
Bodapati Harish 820 Reputation points Microsoft External Staff Moderator

2025-06-18T16:45:39.6666667+00:00
Hi Danny Fournier,

You’re correct that Run-From-Package makes wwwroot read-only, which won’t work if your app needs to write files there. You have two straightforward paths forward:

Move writable files out of wwwroot

Keep Run-From-Package enabled so ZIP extraction and encoding are never an issue, and change your code to write any uploads or logs into a different folder, for example under /home/data or /home/uploads. You can mount an Azure Files share to one of those paths for persistence. Your static files continue to serve from wwwroot, and any dynamic content lives in a write-enabled location.

Take control of the unzip step yourself

Turn off Run-From-Package and keep using zipDeploy, but immediately after deployment run your own unzip command with UTF-8 support instead of relying on KuduSync. In your YAML, add an Azure CLI step before or after your deployment task that does something like this:

- task: AzureCLI@2 displayName: Extract ZIP with UTF-8 support inputs: azureSubscription: '$(azureSubscription)' scriptType: bash scriptLocation: inlineScript inlineScript: | # download the deployed package curl -s -u ${{ secrets.KUDU_USER }}:${{ secrets.KUDU_PASS }} \ https://$(webAppName).scm.azurewebsites.net/api/zip/site/wwwroot \ --output site.zip # clear wwwroot and unpack with proper UTF-8 handling az webapp ssh --name $(webAppName) --resource-group $(azureResourceGroup) \ --command "rm -rf /home/site/wwwroot/* && unzip -O UTF-8 site.zip -d /home/site/wwwroot"

You’ll need Kudu credentials stored securely as pipeline variables or in a service connection. This forces a clean extraction under full UTF-8 support and leaves wwwroot writable at runtime.

Either moving writes outside wwwroot or taking over the unzip process will stop KuduSync from mangling your folder names while still allowing your app to write files. Let me know which approach suits you best, and I can help refine the YAML further.
Danny Fournier 0 Reputation points

2025-06-18T23:22:55.8033333+00:00

Without a doubt, the one where we take over the unzip process would suit us better. I'll note that since our self hosted agent is Windows, shouldn't we be using Powershell? I think I can figure something out if this is the case using existing .ps1 scripts.

Danny Fournier 0

Here's my code/approach below. I'm currently getting a 504. If I'm understanding correctly, by default, timeouts are set to 0/indefinite timeout.

Info on the file I'm using:

Content upload statistics:
Total Content: 218.6 MB
Physical Content Uploaded: 37.9 MB
Logical Content Uploaded: 39.6 MB
Compression Saved: 1.7 MB
Deduplication Saved: 179.0 MB
Number of Chunks Uploaded: 499
Total Number of Chunks: 5,288

Calling REST API URL...
##[error]Response status code does not indicate success: 504 (Gateway Timeout).
##[error]PowerShell exited with code '1'.

param (
    [string] $ResGroupName,
    [string] $WebAppName,
    [string] $ArchivePath,
    [string] $ArchiveName
)

try
{
    Install-Module -Name Az.Websites

    # Get publishing profile for web application
    $WebApp = Get-AzWebApp -Name $WebAppName -ResourceGroupName $ResGroupName
    [xml]$publishingProfile = Get-AzWebAppPublishingProfile -WebApp $WebApp

    # Create Base64 authorization header
    $username = $publishingProfile.publishData.publishProfile[0].userName
    $password = $publishingProfile.publishData.publishProfile[0].userPWD
    $base64AuthInfo = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes(("{0}:{1}" -f $username,$password)))
    $bytes = [System.IO.File]::ReadAllBytes($ArchivePath)

    # -- Upload artifact to app service --
    # Splat all parameters together in $param  
    $param = @{  
                # command REST API url  
                Uri = "https://$WebAppName.scm.xxx.appserviceenvironment.net/api/zip/site/wwwroot"  
                Headers = @{Authorization=("Basic {0}" -f $base64AuthInfo)}  
                Method = "PUT"
                Body = $bytes
                # Body = (Get-Content -Path $ArchivePath -Encoding Byte)

    }  

    Write-Host "Calling REST API URL..."

    # Invoke REST call  
    Invoke-RestMethod @param 

    Write-Host "Called REST API URL..."

    # -- Extract artifact on app service --
    Enter-AzVM -ResourceGroupName $ResGroupName -Name $WebAppName -Command @("unzip -O UTF-8 $ArchiveName -d /home/site/wwwroot")

    Write-Host "Called Enter-AzVM..."

}
catch {
    Write-Error $_
}

Your answer

Siva Nair 2,340 Reputation points Microsoft External Staff Moderator

2025-06-16T18:33:25.81+00:00

Hi Danny Fournier,

Reaching you out in private chat for more details , please check.

The fact that the folder "méli-mélo" ends up as 'm'$'\351''li-m'$'\351''lo' suggests that there's a character encoding mismatch happening during the deployment process.

Here are a few things you can consider to help resolve this:

Make sure that your local environment (where you're preparing the deployment) uses the same character encoding as the Azure environment. Ensure you're using UTF-8 or the encoding that best fits your needs.

When creating your ZIP package for deployment, ensure that the tools you're using to create the ZIP file correctly preserve the folder names and their encodings. Sometimes, using different compression tools can lead to different behaviors.

Since you mentioned that you're using AzureRmWebAppDeployment which utilizes KuduSync, ensure that there aren't any steps where the encoding could be altered. If possible, consider using direct FTP or Kudu ZIP deployment to see if that changes the outcome.

KuduSync should maintain the file metadata, but there could be underlying issues with character support in the deployment process. Check if there are any options or parameters in your pipeline setup that could enforce stricter encoding handling.

As a troubleshooting step, try deploying a different package with similar folder names (but with altered encoding) to see if it behaves the same way. This can help isolate whether the issue is with KuduSync or how the folder names are generated/prepared for deployment.

If you have any further assistant, do let me know.
Gaurav Kumar 780 Reputation points Microsoft External Staff Moderator

2025-06-17T05:35:38.1666667+00:00

Hi @Danny Fournier ,

Just checking in to see if above information was helpful. If you have any further updates on this issue, please feel free to post back.
Danny Fournier 0 Reputation points

2025-06-17T11:23:09.2966667+00:00

Can I get more details on the Kudu ZIP deployment process? The basics on how that would work?

The pipeline, code above, uses available tasks and modules. Unsure how they could be configured to circumvent this issue.

FWIW, all our apps (7) are configured the same way and reuse a lot of base templates (pipelines, pipeline yaml, release pipelines, PHP framework, etc.). However, it seems to be random in terms of the issue cropping up. Some apps don't have any issues, some it's the SBX environment, others is DEV, from the same codebase/commits.
Sampath 3,750 Reputation points Microsoft External Staff Moderator

2025-06-17T11:53:45.6566667+00:00

Hi @Danny Fournier , Refer this MSDOC for Deploy with ZIP deploy UI in Kudu
Danny Fournier 0 Reputation points

2025-06-17T13:11:32.7066667+00:00

Configuring UTF-8 for the app services, you mean going into the Environment Variables? This is the only spot I can see where I can add these.
Sampath 3,750 Reputation points Microsoft External Staff Moderator

2025-06-17T13:27:31.73+00:00

Hi Danny Fournier,
You add like below in azure app.

You’ll need to add LANG and LC_ALL as environment variables in your App Service using the Azure Portal.

Here’s how to do it:

Go to Azure Portal > App Services > select your app > Configuration (under the Settings section) > Application settings tab.

Click on + New application setting, then enter:

- Name: LANG - Value: en_US.UTF-8

Click OK, then add another setting:

- Name: LC_ALL - Value: en_US.UTF-8

After adding both, click Save at the top. Azure will prompt you to restart the app — confirm the restart so the new settings take effect.

These settings ensure that your App Service uses UTF-8 encoding at runtime, which allows special characters in folder names to be handled correctly during deployment.
(or)

Run the following command in Azure Cloud Shell:

az webapp config appsettings set --resource-group <group-name> --name <app-name> --settings SCM_DO_BUILD_DURING_DEPLOYMENT=true

For more information, see Kudu documentation.
Danny Fournier 0 Reputation points

2025-06-17T13:34:10.5466667+00:00

Following these changes (and a restart), when I SSH into the app service, I get:

-bash: warning: setlocale: LC_ALL: cannot change locale (en_US.UTF-8)

Output of locale command:

root@d3a9f59bcd1f:/home# locale LANG=en_US.UTF-8 LANGUAGE=C.UTF-8 LC_CTYPE="C.UTF-8" LC_NUMERIC="C.UTF-8" LC_TIME="C.UTF-8" LC_COLLATE="C.UTF-8" LC_MONETARY="C.UTF-8" LC_MESSAGES="C.UTF-8" LC_PAPER="C.UTF-8" LC_NAME="C.UTF-8" LC_ADDRESS="C.UTF-8" LC_TELEPHONE="C.UTF-8" LC_MEASUREMENT="C.UTF-8" LC_IDENTIFICATION="C.UTF-8" LC_ALL=C.UTF-8
Danny Fournier 0 Reputation points

2025-06-17T17:55:30.7066667+00:00

Noting that "our-agent" is Windows Server 2019 Data Center... perhaps this is where the issue lies? Ubuntu and the app Service have been confirmed as being UTF-8.
Bodapati Harish 820 Reputation points Microsoft External Staff Moderator

2025-06-18T08:59:35.3533333+00:00

Hi Danny Fournier,

Thanks for the thorough recap. Given that your App Service and the final extraction environment are confirmed to support UTF-8, the remaining culprit is where the ZIP archive is created your self-hosted Windows Server 2019 agent. Windows does not reliably embed filenames as UTF-8 in ZIP metadata, even when you use the zip command with Unicode flags. When that archive is unpacked on Linux, the special characters get misread and folders end up with escape sequences instead of proper names.

To solve this once and for all, move the build and ZIP creation step onto a Linux agent. Linux agents natively store filenames in UTF-8, so your “méli-mélo” folder will remain intact through to the App Service. You can leave the deploy job on Windows if you need to, but the archive must be built on Linux.

In your YAML, simply change the Buildjob pool like:

- job: Buildjob pool: vmImage: ubuntu-24.04

Keep all your existing steps, including the zip -r --unicode UTF8 call and the switch to zipDeploy. Once the ZIP is built on Linux, the App Service extract will preserve the correct folder names.
Danny Fournier 0 Reputation points

2025-06-18T10:48:05.4833333+00:00

Really appreciate the feedback!

I wanted to highlight that the job that produces the zip file (ie. BuildJob) already uses Ubuntu. The pool of the job uses the variable $(vmImageName) that has a value of "ubuntu-24.04".

It's the DeployJob that uses the pool "our-agent", which is Windows 2019, from the variable $(azureSelfHostedAgent).

Maybe we need to add a Linux self hosted agent?
Bodapati Harish 820 Reputation points Microsoft External Staff Moderator

2025-06-18T11:47:33.2333333+00:00

Hi Danny Fournier,

Since your build job already runs on Ubuntu and produces a proper UTF-8 ZIP, adding a Linux agent for the deploy job won’t help. The last step that mangles folder names is KuduSync copying files into wwwroot. To eliminate that, use Run-From-Package so the App Service mounts your ZIP directly instead of unpacking and syncing it.

You don’t need to change your build steps or agent pools. Just enable Run-From-Package and keep using zipDeploy:

Enable Run-From-Package in the Azure Portal

Azure Portal > App Services > select your app > Configuration (under Settings) > Application settings tab > + New application setting

Name: WEBSITE_RUN_FROM_PACKAGE

Value: 1

Click OK, then Save and agree to restart the app.

Or add this before deployment in your YAML

- task: AzureCLI@2 displayName: Enable Run-From-Package inputs: azureSubscription: '$(azureSubscription)' scriptType: bash scriptLocation: inlineScript inlineScript: | az webapp config appsettings set \ --name $(webAppName) \ --resource-group $(azureResourceGroup) \ --settings WEBSITE_RUN_FROM_PACKAGE=1

Leave your zipDeploy step as it is. Once Run-From-Package is on, special-character folders like “méli-mélo” will appear correctly, because the ZIP isn’t unpacked with KuduSync. Let me know how it goes
Danny Fournier 0 Reputation points

2025-06-18T12:33:50.76+00:00

Thanks for the reply. I was reading about WEBSITE_RUN_FROM_PACKAGE and found this:

When you run from a package, the wwwroot folder is read-only and you receive an error if you write files to this directory. Files are also read-only in the Azure portal.

This is a stopper for us as we're writing files in wwwroot.
Danny Fournier 0 Reputation points

2025-06-18T23:22:55.8033333+00:00

Without a doubt, the one where we take over the unzip process would suit us better. I'll note that since our self hosted agent is Windows, shouldn't we be using Powershell? I think I can figure something out if this is the case using existing .ps1 scripts.
Danny Fournier 0 Reputation points

2025-06-19T12:02:08.7+00:00

Here's my code/approach below. I'm currently getting a 504. If I'm understanding correctly, by default, timeouts are set to 0/indefinite timeout.

Info on the file I'm using:

Content upload statistics: Total Content: 218.6 MB Physical Content Uploaded: 37.9 MB Logical Content Uploaded: 39.6 MB Compression Saved: 1.7 MB Deduplication Saved: 179.0 MB Number of Chunks Uploaded: 499 Total Number of Chunks: 5,288

Calling REST API URL... ##[error]Response status code does not indicate success: 504 (Gateway Timeout). ##[error]PowerShell exited with code '1'.

param ( [string] $ResGroupName, [string] $WebAppName, [string] $ArchivePath, [string] $ArchiveName ) try { Install-Module -Name Az.Websites # Get publishing profile for web application $WebApp = Get-AzWebApp -Name $WebAppName -ResourceGroupName $ResGroupName [xml]$publishingProfile = Get-AzWebAppPublishingProfile -WebApp $WebApp # Create Base64 authorization header $username = $publishingProfile.publishData.publishProfile[0].userName $password = $publishingProfile.publishData.publishProfile[0].userPWD $base64AuthInfo = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes(("{0}:{1}" -f $username,$password))) $bytes = [System.IO.File]::ReadAllBytes($ArchivePath) # -- Upload artifact to app service -- # Splat all parameters together in $param $param = @{ # command REST API url Uri = "https://$WebAppName.scm.xxx.appserviceenvironment.net/api/zip/site/wwwroot" Headers = @{Authorization=("Basic {0}" -f $base64AuthInfo)} Method = "PUT" Body = $bytes # Body = (Get-Content -Path $ArchivePath -Encoding Byte) } Write-Host "Calling REST API URL..." # Invoke REST call Invoke-RestMethod @param Write-Host "Called REST API URL..." # -- Extract artifact on app service -- Enter-AzVM -ResourceGroupName $ResGroupName -Name $WebAppName -Command @("unzip -O UTF-8 $ArchiveName -d /home/site/wwwroot") Write-Host "Called Enter-AzVM..." } catch { Write-Error $_ }

Share via

Folder encoding issue on Linux App Service using AzureRmWebAppDeployment/KuduSync

Your answer