Troubleshoot Python errors in Azure Functions
Following is a list of troubleshooting guides for common issues in Python functions:
- ModuleNotFoundError and ImportError
- Cannot import 'cygrpc'
- Python exited with code 137
- Python exited with code 139
This section helps you troubleshoot module-related errors in your Python function app. These errors typically result in the following Azure Functions error message:
Exception: ModuleNotFoundError: No module named 'module_name'.
This error occurs when a Python function app fails to load a Python module. The root cause for this error is one of the following issues:
- The package can't be found
- The package isn't resolved with proper Linux wheel
- The package is incompatible with the Python interpreter version
- The package conflicts with other packages
- The package only supports Windows or macOS platforms
View project files
To identify the actual cause of your issue, you need to get the Python project files that run on your function app. If you don't have the project files on your local computer, you can get them in one of the following ways:
- If the function app has
WEBSITE_RUN_FROM_PACKAGEapp setting and its value is a URL, download the file by copy and paste the URL into your browser.
- If the function app has
WEBSITE_RUN_FROM_PACKAGEand it is set to
1, navigate to
https://<app-name>.scm.azurewebsites.net/api/vfs/data/SitePackagesand download the file from the latest
- If the function app doesn't have the app setting mentioned above, navigate to
https://<app-name>.scm.azurewebsites.net/api/settingsand find the URL under
SCM_RUN_FROM_PACKAGE. Download the file by copy and paste the URL into your browser.
- If none of these works for you, navigate to
https://<app-name>.scm.azurewebsites.net/DebugConsoleand reveal the content under
The rest of this article helps you troubleshoot potential causes of this error by inspecting your function app's content, identifying the root cause, and resolving the specific issue.
This section details potential root causes of module-related errors. After you figure out which is the likely root cause, you can go to the related mitigation.
The package can't be found
.python_packages/lib/site-packages/<package-name>. If the file path doesn't exist, this missing path is likely the root cause.
Using third-party or outdated tools during deployment may cause this issue.
The package isn't resolved with proper Linux wheel
.python_packages/lib/site-packages/<package-name>-<version>-dist-info. Use your favorite text editor to open the wheel file and check the Tag: section. If the value of the tag doesn't contain linux, this could be the issue.
Python functions run only on Linux in Azure: Functions runtime v2.x runs on Debian Stretch and the v3.x runtime on Debian Buster. The artifact is expected to contain the correct Linux binaries. Using
--build local flag in Core Tools, third-party, or outdated tools may cause older binaries to be used.
The package is incompatible with the Python interpreter version
.python_packages/lib/site-packages/<package-name>-<version>-dist-info. Using a text editor, open the METADATA file and check the Classifiers: section. If the section doesn't contains
Python :: 3,
Python :: 3.6,
Python :: 3.7,
Python :: 3.8, or
Python :: 3.9, this means the package version is either too old, or most likely, the package is already out of maintenance.
You can check the Python version of your function app from the Azure portal. Navigate to your function app, choose Resource explorer, and select Go.
After the explorer loads, search for LinuxFxVersion, which shows the Python version.
The package conflicts with other packages
If you have verified that the package is resolved correctly with the proper Linux wheels, there may be a conflict with other packages. In certain packages, the PyPi documentations may clarify the incompatible modules. For example in
azure 4.0.0, there's a statement as follows:
This package isn't compatible with azure-storage. If you installed azure-storage, or if you installed azure 1.x/2.x and didn’t uninstall azure-storage, you must uninstall azure-storage first.
You can find the documentation for your package version in
The package only supports Windows or macOS platforms
requirements.txt with a text editor and check the package in
https://pypi.org/project/<package-name>. Some packages only run on Windows or macOS platforms. For example, pywin32 only runs on Windows.
Module Not Found error may not occur when you're using Windows or macOS for local development. However, the package fails to import on Azure Functions, which uses Linux at runtime. This is likely to be caused by using
pip freeze to export virtual environment into requirements.txt from your Windows or macOS machine during project initialization.
The following are potential mitigations for module-related issues. Use the diagnoses above to determine which of these mitigations to try.
Enable remote build
Make sure that remote build is enabled. The way that you do this depends on your deployment method.
Make sure that the latest version of the Azure Functions extension for Visual Studio Code is installed. Verify that
.vscode/settings.json exists and it contains the setting
"azureFunctions.scmDoBuildDuringDeployment": true. If not, please create this file with the
azureFunctions.scmDoBuildDuringDeployment setting enabled and redeploy the project.
Build native dependencies
Make sure that the latest version of both docker and Azure Functions Core Tools is installed. Go to your local function project folder, and use
func azure functionapp publish <app-name> --build-native-deps for deployment.
Update your package to the latest version
Browse the latest package version in
https://pypi.org/project/<package-name> and check the Classifiers: section. The package should be
OS Independent, or compatible with
POSIX :: Linux in Operating System. Also, the Programming Language should contains
Python :: 3,
Python :: 3.6,
Python :: 3.7,
Python :: 3.8, or
Python :: 3.9.
If these are correct, you can update the package to the latest version by changing the line
<package-name>~=<latest-version> in requirements.txt.
Some developers use
pip freeze > requirements.txt to generate the list of Python packages for their developing environments. Although this convenience should work in most cases, there can be issues in cross-platform deployment scenarios, such as developing functions locally on Windows or macOS, but publishing to a function app, which runs on Linux. In this scenario,
pip freeze can introduce unexpected operating system-specific dependencies or dependencies for your local development environment. These dependencies can break the Python function app when running on Linux.
The best practice is to check the import statement from each .py file in your project source code and only check-in those modules in requirements.txt file. This guarantees the resolution of packages can be handled properly on different operating systems.
Replace the package with equivalents
First, we should take a look into the latest version of the package in
https://pypi.org/project/<package-name>. Usually, this package has their own GitHub page, go to the Issues section on GitHub and search if your issue has been fixed. If so, update the package to the latest version.
Sometimes, the package may have been integrated into Python Standard Library (such as pathlib). If so, since we provide a certain Python distribution in Azure Functions (Python 3.6, Python 3.7, Python 3.8, and Python 3.9), the package in your requirements.txt should be removed.
However, if you're facing an issue that it has not been fixed and you're on a deadline. I encourage you to do some research and find a similar package for your project. Usually, the Python community will provide you with a wide variety of similar libraries that you can use.
Troubleshoot cannot import 'cygrpc'
This section helps you troubleshoot 'cygrpc' related errors in your Python function app. These errors typically result in the following Azure Functions error message:
Cannot import name 'cygrpc' from 'grpc._cython'
This error occurs when a Python function app fails to start with a proper Python interpreter. The root cause for this error is one of the following issues:
- The Python interpreter mismatches OS architecture
- The Python interpreter is not supported by Azure Functions Python Worker
Diagnose 'cygrpc' reference error
The Python interpreter mismatches OS architecture
This is most likely caused by a 32-bit Python interpreter is installed on your 64-bit operating system.
If you're running on an x64 operating system, please ensure your Python 3.6, 3.7, 3.8, or 3.9 interpreter is also on 64-bit version.
You can check your Python interpreter bitness by the following commands:
On Windows in PowerShell:
py -c 'import platform; print(platform.architecture())'
On Unix-like shell:
python3 -c 'import platform; print(platform.architecture())'
If there's a mismatch between Python interpreter bitness and operating system architecture, please download a proper Python interpreter from Python Software Foundation.
The Python interpreter is not supported by Azure Functions Python Worker
The Azure Functions Python Worker only supports Python 3.6, 3.7, 3.8, and 3.9.
Please check if your Python interpreter matches our expected version by
py --version in Windows or
python3 --version in Unix-like systems. Ensure the return result is Python 3.6.x, Python 3.7.x, Python 3.8.x, or Python 3.9.x.
If your Python interpreter version does not meet our expectation, please download the Python 3.6, 3.7, 3.8, or 3.9 interpreter from Python Software Foundation.
Troubleshoot Python Exited With Code 137
Code 137 errors are typically caused by out-of-memory issues in your Python function app. As a result, you get the following Azure Functions error message:
Microsoft.Azure.WebJobs.Script.Workers.WorkerProcessExitException : python exited with code 137
This error occurs when a Python function app is forced to terminate by the operating system with a SIGKILL signal. This signal usually indicates an out-of-memory error in your Python process. The Azure Functions platform has a service limitation which will terminate any function apps that exceeded this limit.
Please visit the tutorial section in memory profiling on Python functions to analyze the memory bottleneck in your function app.
Troubleshoot Python Exited With Code 139
This section helps you troubleshoot segmentation fault errors in your Python function app. These errors typically result in the following Azure Functions error message:
Microsoft.Azure.WebJobs.Script.Workers.WorkerProcessExitException : python exited with code 139
This error occurs when a Python function app is forced to terminate by the operating system with a SIGSEGV signal. This signal indicates a memory segmentation violation which can be caused by unexpectedly reading from or writing into a restricted memory region. In the following sections, we provide a list of common root causes.
A regression from third-party packages
In your function app's requirements.txt, an unpinned package will be upgraded to the latest version in every Azure Functions deployment. Vendors of these packages may introduce regressions in their latest release. To recover from this issue, try commenting out the import statements, disabling the package references, or pinning the package to a previous version in requirements.txt.
Unpickling from a malformed .pkl file
If your function app is using the Python pickel library to load Python object from .pkl file, it is possible that the .pkl contains malformed bytes string, or invalid address reference in it. To recover from this issue, try commenting out the pickle.load() function.
Pyodbc connection collision
If your function app is using the popular ODBC database driver pyodbc, it is possible that multiple connections are opened within a single function app. To avoid this issue, please use the singleton pattern and ensure only one pyodbc connection is used across the function app.
Troubleshoot errors with Protocol Buffers
Version 4.x.x of the Protocol Buffers (protobuf) package introduces breaking changes. Because the Python worker process for Azure Functions relies on v3.x.x of this package, pinning your function app to use v4.x.x can break your app. At this time, you should also avoid using any libraries that themselves require protobuf v4.x.x.
Example error logs:
[Information] File "/azure-functions-host/workers/python/3.8/LINUX/X64/azure_functions_worker/protos/shared/NullableTypes_pb2.py", line 38, in <module> [Information] _descriptor.FieldDescriptor( [Information] File "/home/site/wwwroot/.python_packages/lib/site-packages/google/protobuf/descriptor.py", line 560, in __new__ [Information] _message.Message._CheckCalledFromGeneratedFile() [Error] TypeError: Descriptors cannot not be created directly. [Information] If this call came from a _pb2.py file, your generated code is out of date and must be regenerated with protoc >= 3.19.0. [Information] If you cannot immediately regenerate your protos, some other possible workarounds are: [Information] 1. Downgrade the protobuf package to 3.20.x or lower. [Information] 2. Set PROTOCOL_BUFFERS_PYTHON_IMPLEMENTATION=python (but this will use pure-Python parsing and will be much slower). [Information] More information: https://developers.google.com/protocol-buffers/docs/news/2022-05-06#python-updates
There are two ways to mitigate this issue.
- Set the application setting PYTHON_ISOLATE_WORKER_DEPENDENCIES to a value of
- Pin protobuf to a non-4.x.x. version, as in the following example:
protobuf >= 3.19.3, == 3.*
If you're unable to resolve your issue, please report this to the Functions team:
Submit and view feedback for