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

GA (Java 8)

GA (Java 11 & 8)

GA (Java 11 & 8)

PowerShell

GA (PowerShell Core 6)

GA (PowerShell 7.0 & Core 6)

GA (PowerShell 7.0)

Python

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

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:

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...

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!