Startup problem when running TeamCity server in Azure App Service with Storage Account Mounts
Dear Forum,
We are running TC in linux Azure App Service, utilizing a file-share from an Azure storage account to act as the TC data directory. (More precisely described by the terraform snippet below)
resource "azurerm_linux_web_app" "teamcity" {
site_config {
application_stack {
docker_image_name = "jetbrains/teamcity-server:2025.03-linux"
docker_registry_url = "https://index.docker.io"
}
}storage_account {
account_name = ${some_azure_storage_account}
name = "data"
share_name = "${some_azure_file_share}
type = "AzureFiles"
mount_path = "/data/teamcity_server/datadir"
}
}
And we are having a problem during server start.
TC “Cannot delete directory '/data/teamcity_server/datadir/system/caches/jdbc'” and refuses to start. I can see that the server was anticipating some problems, but “even after fixing permissions”, it still fails.
[2025-04-12 02:24:37,522] INFO - jetbrains.buildServer.STARTUP - Database properties file "/data/teamcity_server/datadir/config/database.properties" exists
[2025-04-12 02:24:37,535] INFO - jetbrains.buildServer.STARTUP - Internal HSQL database file (/data/teamcity_server/datadir/system/buildserver.data) doesn't exist
[2025-04-12 02:24:37,548] INFO - jetbrains.buildServer.STARTUP - Database connection URL: jdbc:sqlserver://${redacted_sql_connection_string};
[2025-04-12 02:24:37,562] INFO - jetbrains.buildServer.STARTUP - Using external (MSSQL) database
[2025-04-12 02:24:37,583] INFO - jetbrains.buildServer.STARTUP - Current stage: Connecting to the database
[2025-04-12 02:24:37,621] INFO - jetbrains.buildServer.STARTUP - JDBC loader: loading JDBC drivers (for the first time)
[2025-04-12 02:24:38,031] WARN - ains.buildServer.util.FileUtil - Cannot delete directory '/data/teamcity_server/datadir/system/caches/jdbc'
[2025-04-12 02:24:38,045] WARN - ains.buildServer.util.FileUtil - Cannot delete directory '/data/teamcity_server/datadir/system/caches/jdbc' even after fixing permissions
The file mount is working, because it can find `/data/teamcity_server/datadir/config/database.properties` just fine.
Restarting the docker instance (in Azure App Service) fixes it. But this is undesirable because it requires an intervention from the Azure level.
So, is there any additional switches I can use with the TC docker image to prevent this type of error? e.g. can I use a sessional cache? (/data/teamcity_server/datadir/system/caches-${rand_hex}/jdbc) or why do I need a “cache” anyhow?
Please sign in to leave a comment.
Hi Joshua,
It appears you're facing a known issue when using Azure Files (CIFS/SMB) as a mounted volume with TeamCity, a Java-based application that expects a fully POSIX-compliant file system. Key file system features such as file locking, atomic operations, and delete-on-close behavior are not reliably supported by Azure Files, which can lead to unexpected failures.
TeamCity requires persistent storage and stable file system behavior for its Data Directory to function correctly. It assumes reliable read/write access to this directory at all times. If the Data Directory becomes temporarily inaccessible, it can lead to functional issues or even data corruption, especially for running builds. While TeamCity is designed to tolerate occasional disruptions, certain operations (such as caching) are sensitive and may fail in non-compliant environments.
Specifically, it is recommended to keep
<TeamCity Data Directory>/system/cacheson a local disk, rather than on a network file share. This is because caching operations are I/O-intensive and rely on behaviors that network-mounted file systems like Azure Files cannot always guarantee.In typical deployments — such as VMs, Docker containers, or Kubernetes clusters (e.g., via Azure Kubernetes Service) — local storage is used for volatile components like caches. While mounting Azure Files is possible and can be useful for configuration or logs, it is not ideal for cache directories or other high-throughput file operations.
For more details about TeamCity's data directory structure and requirements, refer to the official documentation: https://www.jetbrains.com/help/teamcity/teamcity-data-directory.html#Recommendations+as+to+choosing+Data+Directory+Location
Consider moving to AKS or dedicated Linux VMs for production usage.
Best Regards,
Tom
Tom,
Thank you for the article. I agree with your diagnosis.
Our existing website hosting infrastructure is entirely App Service. Unfortunately, we are not ready to change the way we deploy TC wholesale yet. But I recognize that you have done your part. The decision of sticking with App Service is on me.
With that said, App Service docker does have a local directory (I believe that folder survive docker reboot, but not container host reboot.) But I believe that will be okay as a “cache” location since TC does not expect cache to be persistent between process restarts, it just wants it to be responsive and available.
So, my workaround is to set a different cache to the local “~” home directory. I continue to use the Azure Storage Account as the <TeamCity Data Directory>. And so far, it seems to be holding together. Hopefully this works in the long run (too early to tell)…
Based on my testing, changing the App Service Plan for the App Service requires reconfiguring TeamCity settings, including the data directory and database. Just for your reference.
Setting the cache to local might be an option, but it doesn't guarantee TeamCity's stability if the data directory is located on an Azure File Share.
Best Regards,
Tom