Issues you may meet when upgrading Azure function app to V4

[XinyuShan]

This blog will talk about some common issues you may meet when you try to upgrade your Azure function from older runtime version to newer (eg. ~4) and the causes/resolutions.

Public Doc:

Blog Function v4 VS v3: https://techcommunity.microsoft.com/t5/apps-on-azure-blog/azure-functions-v4-versus-v3/ba-p/3276055

Migrate from 3.x to 4.x: https://docs.microsoft.com/en-us/azure/azure-functions/functions-versions?tabs=in-process%2Cv4&pivot...

Migrate from 2.x to 3.x: https://docs.microsoft.com/en-us/azure/azure-functions/functions-versions?tabs=in-process%2Cv4&pivot...

Known issues: https://docs.microsoft.com/en-us/azure/azure-functions/functions-versions?tabs=in-process%2Cv4&pivot...

[Issue 1] Runtime warning message on portal

To upgrade your function App, you set the FUNCTIONS_EXTENSION_VERSION to "~4".

You may observe below warning message and the runtime version got set to "custom" rather than "~4".

"Your app is pinned to an unsupported runtime version for 'xxx'. For better performance, we recommend using one of our supported versions instead: xxx."

Troubleshooting:

1. Access https://resources.azure.com/ to check the runtime stack version

2. If FUNCTIONS_WORKER_RUNTIME is set to "dotnet", check the value of "netFrameworkVersion".

If set to "powershell", check "powerShellVersion". Same for other programming languages.

3. Refer to below table, if for function v4, "netFrameworkVersion" is "v4.0" or "powerShellVersion" is "~6", those language stack versions are unsupported in V4, you'll then see the warning message on portal and runtime got set to "custom" automatically.

Language	1.x	2.x	3.x	4.x
C#	GA (.NET Framework 4.8)	GA (.NET Core 2.11)	GA (.NET Core 3.1) GA (.NET 5.0)	GA (.NET 6.0)
JavaScript	GA (Node.js 6)	GA (Node.js 10 & 8)	GA (Node.js 14, 12, & 10)	GA (Node.js 14) GA (Node.js 16)
F#	GA (.NET Framework 4.8)	GA (.NET Core 2.11)	GA (.NET Core 3.1)	GA (.NET 6.0)
Java	N/A	GA (Java 8)	GA (Java 11 & 8)	GA (Java 11 & 8)
PowerShell	N/A	GA (PowerShell Core 6)	GA (PowerShell 7.0 & Core 6)	GA (PowerShell 7.0)
Python	N/A	GA (Python 3.7 & 3.6)	GA (Python 3.9, 3.8, 3.7, & 3.6)	GA (Python 3.9, 3.8, 3.7)
TypeScript2	N/A	GA	GA	GA

Soft reminder:

For .NET function app,  function runtime

• [~2] your app will be automatically upgraded to run on .NET Core 3.1, which is a long-term support version of .NET Core 3. (Even if it mention .NET Core is only supported for 3.x.
• [~2.0] You could choose to pin to "~2.0" to stay with .NET Core 2.2. Ref

Cause:

Your V3 function app's netFrameWorkVersion has been on .NET 4.0.  Function V4 runtime requires .NET 6.0. The platform didn’t update it automatically, this is to avoid breaking customer’s applications who uses any method/type unsupported in .NET 6.0.

We'll leave this .NET version upgrade action(updating "netFrameworkVersion") to customers, and with the warning message to remind that the function v4 will need .NET 6.0. You could then decide if the function is ready to be upgraded to v4 from older runtime version.

Resolution:

For dotnet app

======================================

• Use Azure CLI cmds to update "netFrameworkVersion" in app config for app or app slots:

az functionapp config set --net-framework-version v6.0 -n <APP_NAME> -g <RESOURCE_GROUP_NAME>
az functionapp config set --net-framework-version v6.0 -n <APP_NAME> -g <RESOURCE_GROUP_NAME> --slot <SLOT_NAME>​

• Or use resource explorer resources.azure.com -> find web app -> config -> web -> netFrameworkVersion update to V6.0.

For other languages

======================================

• You could update the language version on portal too

Also please make sure your local project is compatible with your selected language version.

Reference:

Actions needed for upgrading to V4 https://docs.microsoft.com/en-us/azure/azure-functions/functions-versions?tabs=in-process%2Cv4&pivot...

[Issue 2] Function App returns 503 Server unavailable

After upgrading your function App to "~4", the function app started to give 503 errors.

Troubleshooting:

503 server error for function app may indicate a host related issue such as "host failed to start up". If your function app enables app insight, you could run below query to get more error details:

traces
| where severityLevel >= 2

In some cases, we find the error which caused host to fail as below:

Spoiler

Microsoft.Azure.WebJobs.Script.HostInitializationException : One or more loaded extensions do not meet the minimum requirements. For more information see https://aka.ms/func-min-extension-versions.

ExtensionStartupType EventHubsWebJobsStartup from assembly 'Microsoft.Azure.WebJobs.EventHubs, Version=4.1.1.0, Culture=neutral, PublicKeyToken=xxx' does not meet the required minimum version of 4.3.0.0. Update your NuGet package reference for Microsoft.Azure.WebJobs.Extensions.EventHubs to 4.3.0 or later.

ExtensionStartupType CosmosDBWebJobsStartup from assembly 'Microsoft.Azure.WebJobs.Extensions.CosmosDB, Version=3.0.5.0, Culture=neutral, PublicKeyToken=xxxx' does not meet the required minimum version of 3.0.9.0. Update your NuGet package reference for Microsoft.Azure.WebJobs.Extensions.CosmosDB to 3.0.9 or later.

Cause:

Function V4 required a minimum version for supported extensions. The functions host will enforce the proposed minimum versions in the table below. If an older version of one of the following extensions is present, the host will throw an error specifying the minimum required version and fail to start.

Resolution:

For dotnet app

======================================

Please do a set of NuGet updates to get the supported extensions installed for affected extensions.

For other languages

======================================

Please upgrade to extension bundle version 2.x or later

Reference:

Function V4 required a minimum version for supported extensions: https://github.com/Azure/Azure-Functions/issues/1987

[Issue 3] Function v4 fallback to V2

Your function app is built with V4 runtime locally, but when you try to deploy it via Cloud Shell, you observe below warning. The deployment completed but app responded 502/503. Your app's still using runtime V2 rather than V4.

"You're trying to publish to a non-v2 function app from v2 tooling.
You can pass --force to force update the app to v2, or switch to v1 or v3 tooling for publishing"

Cause:

The publish tooling Azure  Function Core tools version needs to be aligned with function app's runtime version.

• Develop app v3 -> 3.x Core Tools
• Develop app v4 -> 4.x Core Tools

There're other changes needed for VS Code.

Resolution:

 1.   Upgrade function app runtime version via Azure CLI or portal app setting change:

az functionapp config appsettings set --name <FUNCTION_APP> \
--resource-group <RESOURCE_GROUP> \
--settings FUNCTIONS_EXTENSION_VERSION=<VERSION>

 2.  Upgrade function core tool to version 4.x.

npm i -g azure-functions-core-tools@4 --unsafe-perm true

Reference:

View and update current runtime version: https://docs.microsoft.com/en-us/azure/azure-functions/set-runtime-version?tabs=azurecli#view-and-up...

[Issue 4] Function v4 host failed to start up due to host ID collision

Your function app is upgraded to V4 runtime, you migrated function app to use corresponding language version and updated with the latest SDK such as Azure.Messasing.ServiceBus library too. But the app has below issues:

1. 500/503 Service is unavailable
2. You observed error in App insight logs/diagnose and solve problem -> Function App down or reporting errors

 "A collision for Host ID 'xxxx' was detected in the configured storage account. For more information, see https://aka.ms/functions-hostid-collision."

Cause:

Your function app name has more than 32 characters and it's using a storage account shared with other function apps.

• Starting with version 3.x of the Functions runtime, host ID collision is detected and a warning is logged.
• In version 4.x, an error is logged and the host is stopped, resulting in a hard failure to prevent the host from starting. Ref for more details.

The Functions Host uses a Host ID to uniquely identify a particular Function App. By default, the ID is auto-generated from the Function App name, by taking the first 32 characters. This ID is then used when storing per-app correlation and tracking information in the linked storage account. When you have function apps with names longer than 32 characters and when the first 32 characters are identical, this truncation can result in duplicate host ID values. When two function apps with identical host IDs use the same storage account, you may get a host ID collision because stored data can't be uniquely linked to the correct function app.

To prevent this kind of issue, in version 4.x, host ID collision is detected an error is logged, and the host is shut down (hard failure).

Resolution:

You may choose one of below options:

1. Point your app at a different storage account. [Best practice]
2. Rename your app to something less than 32 characters in length. This will change the computed Host ID for the app and remove the collision. [Most recommended]
3. Provide an explicit Host ID for your app(s) so they don't conflict anymore, via app setting AzureFunctionsWebHost__hostId.
4. In the case of v4 hard failure, you can disable this error via the FUNCTIONS_HOSTID_CHECK_LEVEL app setting. Only do this if none of the options above are possible for you. Possible values for this setting are "Warning" and "Error". [Last choice to bypass the warning]

 

Note:

For the 3rd option to customize hostID using app setting AzureFunctionsWebHost__hostId, you might seeing warning in Azure portal or logs saying that it is not recommended to overwrite it, such as "Host id explicitly set in configuration. This is not a recommended configuration and may lead to unexpected behavior."

No worries for the warning. If the you’ve done this in accordance with this guidance, the app will be fine. This is one of the workaround options. PG has emitted this warning when the host ID is explicitly set because it’s not the default configuration. For example, if application slots are used, you need to set different hostID values for those slots.

If the condition allows, the most recommended resolution will be to shorten the app names, but not required.

Reference:

Public wiki regarding host collision:  https://github.com/Azure/azure-functions-host/wiki/Host-IDs#host-id-collisions

App setting AzureFunctionsWebHost__hostId:  https://docs.microsoft.com/en-us/azure/azure-functions/functions-app-settings#azurefunctionswebhost_...

Function host reminder public documentation:  https://docs.microsoft.com/en-us/azure/azure-functions/storage-considerations#host-id-considerations

Github discussion regarding host collision:  https://github.com/Azure/azure-functions-host/issues/2015

Most of above actions are mentioned in doc such as

• Update app setting
• Update .net framework version
• Update nuget package reference version
• Update Azure Core Tools Version
• …

Nowadays, migration across different runtime version is safer and more convenient, and doesn't require significant code change. Just need a little bit more attention to the related tools/packages upgrade, then all will be good!

Feel free to comment below if you've any other questions!