다음을 통해 공유

Azure Functions에서 Python 오류 문제 해결

이 문서에서는 Azure Functions에서 Python 함수의 오류 문제를 해결하는 데 도움이 되는 정보를 제공합니다. 이 문서는 v1 및 v2 프로그래밍 모델을 모두 지원합니다. 문서 상단의 선택기를 통해 사용할 모델을 선택할 수 있습니다.

참고

Python v2 프로그래밍 모델을 사용하려면 반드시 4.x 버전의 함수 런타임이 필요합니다. 자세한 내용은 Azure Functions 런타임 버전 개요를 참조하세요.

Python 함수 사용 시 자주 발생하는 문제들과 그 해결 방법을 다루는 섹션입니다.

특히 v2 모델의 경우 일부 알려진 문제 및 해결 방법은 다음과 같습니다.

Python Functions에 대한 일반적인 문제 해결 가이드는 다음과 같습니다.

문제 해결: ModuleNotFoundError

이 섹션에서는 Python 함수 앱의 모듈 관련 오류를 진단하고 해결하는 방법을 안내합니다. 이와 같은 오류가 발생하면 Azure Functions에서 다음과 같은 오류 메시지가 표시됩니다.

예외: ModuleNotFoundError: 'module_name'이라는 모듈이 없습니다.

Python 함수 앱이 필요한 Python 모듈을 불러오지 못할 때 이 오류가 발생합니다. 이 오류의 근본 원인은 다음과 같은 문제 중 하나입니다.

프로젝트 파일 보기

문제의 실제 원인을 확인하려면 함수 앱에서 실행되는 Python 프로젝트 파일을 가져와야 합니다. 로컬 컴퓨터에 프로젝트 파일이 없다면, 다음의 방법들을 통해 이를 가져올 수 있습니다.

  • 함수 앱의 WEBSITE_RUN_FROM_PACKAGE 앱 설정에서 URL 값을 찾으면, 그 URL을 복사하여 브라우저에 붙여넣고 파일을 다운로드할 수 있습니다.
  • 함수 앱의 WEBSITE_RUN_FROM_PACKAGE가 1로 설정된 경우 https://<app-name>.scm.azurewebsites.net/api/vfs/data/SitePackages로 이동하여 최신 href URL에서 파일을 다운로드합니다.
  • 함수 앱에 위와 같은 앱 설정이 구성되어 있지 않다면, https://<app-name>.scm.azurewebsites.net/api/settings 로 이동한 뒤 SCM_RUN_FROM_PACKAGE에서 해당 URL을 확인하시기 바랍니다. 브라우저의 주소창에 URL을 붙여넣으면 파일을 다운로드할 수 있습니다.
  • 제안된 방법으로 문제가 해결되면, https://<app-name>.scm.azurewebsites.net/DebugConsole 로 이동하여 /home/site/wwwroot에서 해당 콘텐츠를 확인하게 됩니다.

본문의 이어지는 내용을 통해 함수 앱의 콘텐츠를 점검하고, 오류의 근본 원인을 파악하여 특정 문제를 해결하는 구체적인 방법을 확인하실 수 있습니다.

ModuleNotFoundError 진단

이 섹션에서는 모듈 관련 오류의 잠재적 근본 원인을 자세히 설명합니다. 가능한 근본 원인을 파악한 후 관련된 완화 방법으로 이동할 수 있습니다.

패키지를 찾을 수 없습니다.

.python_packages/lib/python3.6/site-packages/<package-name> 또는 .python_packages/lib/site-packages/<package-name>로 이동합니다. 파일 경로가 없다면, 이것이 근본 원인이 될 수 있습니다.

배포 과정에서 서드파티 도구나 구버전 도구를 사용할 경우 이러한 문제가 발생할 가능성이 있습니다.

이 문제를 완화하려면 원격 빌드 사용 또는 네이티브 종속성 빌드를 참조하세요.

Linux 휠을 적절히 찾지 못해 패키지 설치 문제를 해결할 수 없는 상황입니다.

.python_packages/lib/python3.6/site-packages/<package-name>-<version>-dist-info 또는 .python_packages/lib/site-packages/<package-name>-<version>-dist-info로 이동합니다. 자주 사용하는 텍스트 편집기를 사용하여 휠 파일을 열고 태그: 섹션을 확인합니다. 태그 값에 linux가 포함되지 않았을 가능성이 있습니다.

Azure에서 Python 함수는 Linux 환경에서만 실행 가능합니다. 함수 런타임 v2.x는 Debian Stretch에서 실행되며, v3.x 런타임은 Debian Buster에서 실행됩니다. 아티팩트는 적절한 Linux 실행 파일을 포함해야 합니다. 핵심 도구에서 --build local 플래그를 사용하지 않으면 타사 또는 오래된 이진 파일이 대신 사용될 수 있습니다.

이 문제를 완화하려면 원격 빌드 사용 또는 네이티브 종속성 빌드를 참조하세요.

패키지가 Python 인터프리터 버전과 호환되지 않습니다.

.python_packages/lib/python3.6/site-packages/<package-name>-<version>-dist-info 또는 .python_packages/lib/site-packages/<package-name>-<version>-dist-info로 이동합니다. 텍스트 편집기에서 메타데이터 파일을 열고 분류자: 섹션을 확인합니다. 섹션에 Python :: 3, Python :: 3.6, Python :: 3.7, Python :: 3.8 또는 Python :: 3.9가 포함되어 있지 않다면, 패키지 버전이 구식이거나 더 이상 유지 보수가 이루어지지 않는 것일 수 있습니다.

Azure Portal을 통해 함수 앱에 설정된 Python 버전을 확인할 수 있습니다. 함수 앱의 개요 페이지에서 런타임 버전을 확인할 수 있습니다. Python 버전 지원 사항은 Azure Functions 런타임 버전 개요를 참고하시기 바랍니다.

이 문제를 해결하려면 패키지를 최신 버전으로 업데이트 하거나, 다른 패키지로 교체하는 방법을 참고하시기 바랍니다.

패키지가 다른 패키지와 충돌합니다.

적절한 Linux 휠을 사용하는 패키지가 올바르게 해결되었다면, 다른 패키지와의 충돌 가능성을 확인해야 합니다. 일부 패키지의 경우 PyPi 설명서에 실제로는 호환되지 않는 모듈이 기재되어 있을 가능성이 있습니다. 예를 들어, azure 4.0.0에서 다음 문을 찾습니다.

이 패키지는 azure-storage와의 호환성을 지원하지 않습니다. azure-storage 패키지가 이미 설치되어 있거나, azure 1.x/2.x 버전을 설치한 후 azure-storage를 삭제하지 않았다면, 우선 azure-storage 패키지를 제거하는 작업이 필요합니다.

https://pypi.org/project/<package-name>/<package-version>에서 패키지 버전에 대한 설명서를 찾을 수 있습니다.

이 문제를 해결하려면 패키지를 최신 버전으로 업데이트 하거나, 다른 패키지로 교체하는 방법을 참고하시기 바랍니다.

이 패키지는 Windows와 macOS 플랫폼에서만 사용할 수 있습니다.

텍스트 편집기를 사용하여 requirements.txt를 열고 https://pypi.org/project/<package-name>에서 패키지를 확인합니다. 일부 패키지의 경우 Windows와 macOS 환경에서만 동작합니다. 예를 들어, pywin32는 Windows 환경에서만 작동합니다.

Windows나 macOS에서 로컬 개발을 진행할 때는 Module Not Found 오류가 발생하지 않을 수 있습니다. 다만 Linux 기반의 Azure Functions 런타임 환경에서는 패키지를 정상적으로 불러오지 못할 수 있습니다. Windows 또는 macOS 컴퓨터에서 프로젝트를 초기화할 때 pip freeze 를 이용하여 가상 환경을 requirements.txt 로 내보내면 이 문제가 발생할 수 있습니다.

문제를 해결하려면 패키지를 해당 항목으로 교체 하거나, requirements.txt 파일을 직접 수정하여 참조하시기 바랍니다.

ModuleNotFoundError 완화

모듈과 관련된 문제를 해결하기 위한 잠재적 방안은 다음과 같습니다. 앞서 진단한 내용을 바탕으로 다음의 완화 방법들을 확인하고 직접 시도해 보시기 바랍니다.

원격 빌드 사용

원격 빌드 기능이 활성화되어 있는지 확인하세요. 배포 방법의 종류에 따라 확인하는 절차가 달라집니다.

Azure Functions extension for Visual Studio Code이 최신 버전으로 설치되어 있는지 확인하세요. .vscode/settings.json 파일이 있고 "azureFunctions.scmDoBuildDuringDeployment": true 설정이 포함되어 있는지 확인합니다. 만약 파일이 존재하지 않는다면, 새 파일을 생성하고 azureFunctions.scmDoBuildDuringDeployment 설정을 활성화한 뒤 프로젝트를 다시 배포하시기 바랍니다.

네이티브 종속성 빌드

Docker 및 Azure Functions Core Tools가 모두 최신 버전으로 설치되어 있는지 확인합니다. 로컬 함수 프로젝트 폴더로 이동한 후, func azure functionapp publish <app-name> --build-native-deps 를 활용하여 배포를 진행합니다.

패키지를 최신 버전으로 업데이트

최신 패키지 버전의 https://pypi.org/project/<package-name>에서 분류자: 섹션을 확인합니다. 패키지는 OS Independent이거나, POSIX에서 POSIX :: Linux 또는 와 호환되어야 합니다. 또한 프로그래밍 언어에는 Python :: 3, Python :: 3.6, Python :: 3.7, Python :: 3.8 또는 Python :: 3.9가 반드시 포함되어야 합니다.

이러한 패키지 항목이 올바른 경우 <package-name>~=<latest-version>의 줄 requirements.txt을 변경하여 패키지를 최신 버전으로 업데이트할 수 있습니다.

수작업 requirements.txt

일부 개발자들은 pip freeze > requirements.txt 를 통해 개발 환경에 필요한 Python 패키지 목록을 작성합니다. 이러한 편의성은 대부분의 상황에서 문제없이 작동하지만, Windows나 macOS 환경에서 로컬 개발을 진행한 후 Linux 기반 함수 앱으로 배포하는 등 플랫폼 간 배포 시나리오에서는 오류가 발생할 수 있습니다. 이러한 시나리오가 발생하면 pip freeze 로 인해 로컬 개발 환경이 특정 운영 체제에 예기치 않게 종속될 위험이 있습니다. Linux 환경에서 실행되는 Python 함수 앱은 이러한 종속성으로 인해 중단될 수 있습니다.

모범 사례는 프로젝트의 각 .py 파일에서 import 문을 검토한 후, requirements.txt 파일에 실제로 필요한 모듈만 포함시키는 것입니다. 이를 통해 여러 운영 체제 환경에서도 패키지 관련 문제를 효과적으로 해결할 수 있습니다.

패키지를 해당 항목으로 바꾸기

먼저 https://pypi.org/project/<package-name>에서 최신 버전의 패키지를 확인합니다. 이러한 패키지들은 대개 독자적인 GitHub 페이지를 보유하고 있습니다. GitHub의 문제 섹션에서 해당 문제의 해결 여부를 확인합니다. 문제가 해결되었다면 패키지를 최신 버전으로 업데이트하세요.

경우에 따라 패키지가 Python 표준 라이브러리(예: pathlib)에 통합될 수 있습니다. Azure Functions(Python 3.6, 3.7, 3.8, 3.9)와 통합된 환경에서는 특정 Python 배포판이 기본 제공되므로, requirements.txt 에서 해당 패키지들을 삭제해야 합니다.

하지만 문제가 해결되지 않은 채 마감일이 임박했다면, 프로젝트에 적합한 대체 패키지를 찾기 위한 조사를 진행하는 것이 현명합니다. Python 커뮤니티에서는 다양한 유사 라이브러리를 손쉽게 활용할 수 있습니다.

종속성 격리 플래그 사용 안 함

애플리케이션 설정 PYTHON_ISOLATE_WORKER_DEPENDENCIES를 0 값으로 설정합니다.

문제 해결: 'cygrpc'를 가져올 수 없음

이 섹션에서는 Python 함수 앱에서 발생하는 cygrpc 관련 오류를 진단하고 해결하는 방법을 설명합니다. 이와 같은 오류가 발생하면 Azure Functions에서 다음과 같은 오류 메시지가 표시됩니다.

'grpc._cython'에서 이름 'cygrpc'를 가져올 수 없음

Python 함수 앱이 올바른 Python 인터프리터를 실행하지 못할 때 이 오류가 나타납니다. 이 오류의 근본 원인은 다음과 같은 문제 중 하나입니다.

'cygrpc' 참조 오류 진단

이 섹션에서는 cygrpc 을 참조하는 오류를 유발할 수 있는 다양한 원인들을 상세히 다룹니다.

Python 인터프리터와 운영체제 아키텍처 간의 불일치가 발생했습니다

64비트 운영 체제에 32비트 Python 인터프리터가 설치된 경우 이러한 불일치가 발생할 수 있습니다.

x64 운영 체제에서 실행할 계획이라면, Python 3.6, 3.7, 3.8, 3.9 인터프리터의 64비트 버전이 설치되어 있는지 먼저 확인해야 합니다.

Python 인터프리터의 비트 수는 다음 명령어를 통해 확인 가능합니다.

Windows PowerShell에서 py -c 'import platform; print(platform.architecture()[0])'를 실행합니다.

Unix와 유사한 셸에서 python3 -c 'import platform; print(platform.architecture()[0])'를 실행합니다.

Python 인터프리터의 비트 수가 운영 체제 아키텍처와 맞지 않다면, Python Software Foundation에서 호환되는 Python 인터프리터를 다운로드해야 합니다.

Azure Functions Python Worker가 Python 인터프리터를 지원하지 않음

Azure Functions Python 작업자는 특정 Python 버전만 지원합니다.

Windows의 py --version 또는 Unix와 유사한 시스템에서 Python 인터프리터가 python3 --version 로 실행될 때 예상 버전과 일치하는지 확인합니다. 반환된 결과가 현재 지원되는 Python 버전과 호환되는지 확인하시기 바랍니다.

Azure Functions의 요구 사항과 맞지 않는 Python 인터프리터 버전을 사용 중이라면, Python Software Foundation에서 Functions가 지원하는 버전을 다운로드하세요.

문제해결: 코드 137로 종료된 Python

Python 함수 앱에서 코드 137 오류가 발생하는 주된 원인은 메모리 부족 문제입니다. 그 결과 다음과 같은 Azure Functions 오류 메시지가 표시됩니다.

Microsoft.Azure.WebJobs.Script.Workers.WorkerProcessExitException: Python이 코드 137로 종료됨

운영 체제에서 SIGKILL 신호를 통해 Python 함수 앱을 강제 종료할 때 이 오류가 발생합니다. 해당 신호는 일반적으로 Python 프로세스의 메모리 부족 오류를 나타냅니다. Azure Functions 플랫폼은 리소스 제한을 초과하는 함수 앱을 자동으로 중단하는 서비스 제한 을 운영하고 있습니다.

로컬 개발 환경에서 Python 함수 앱의 프로필을 확인하여 함수 앱의 메모리 병목 현상을 분석할 수 있습니다.

문제해결: 코드 139로 종료된 Python

이 섹션에서는 Python 함수 앱의 구분 오류를 해결하는 방법을 안내합니다. 이와 같은 오류가 발생하면 Azure Functions에서 다음과 같은 오류 메시지가 표시됩니다.

Microsoft.Azure.WebJobs.Script.Workers.WorkerProcessExitException: Python이 코드 139로 종료됨

운영 체제에서 SIGSEGV 신호를 통해 Python 함수 앱을 강제 종료할 때 이 오류가 발생합니다. 이 신호는 메모리 보호 경계를 벗어난 접근을 나타내며, 할당된 메모리 영역 밖에서 의도하지 않은 읽기 또는 쓰기 작업이 나타날 때 발생합니다. 다음 섹션에서는 흔히 발생하는 근본 원인들을 살펴보겠습니다.

타사 패키지로부터의 회귀

함수 앱의 requirements.txt 파일에서 고정을 해제한 패키지의 경우, Azure 배포 시 자동으로 최신 버전이 적용됩니다. 패키지 업데이트 과정에서 앱의 기능을 저하시키는 회귀 현상이 발생할 수 있습니다. 이 문제를 해결하려면 가져오기 구문을 주석 처리하거나, 패키지 참조를 비활성화하거나, requirements.txt 파일에서 패키지 버전을 이전 상태로 고정해야 합니다.

잘못된 형식의 .pkl 파일에서 언피클링

함수 앱에서 Python 피클 라이브러리를 통해 .pkl 파일로부터 Python 개체를 로드할 때, 해당 파일에 잘못된 형식의 바이트 문자열이나 유효하지 않은 주소 참조가 포함되어 있을 수 있습니다. 해당 문제를 해결하기 위해서는 pickle.load() 함수를 주석 처리하면 됩니다.

Pyodbc 연결 충돌

함수 앱이 ODBC 데이터베이스 드라이버 pyodbc를 사용하는 경우 단일 함수 앱 내에서 여러 연결이 열릴 수 있습니다. 이 문제를 해결하기 위해서는 싱글톤 패턴을 적용하여 함수 앱 전체에서 단 하나의 pyodbc 연결만 사용하도록 해야 합니다.

팁 (조언)

기본 제공 Microsoft Entra 인증 지원을 제공하고 수동 ODBC 드라이버 관리가 필요하지 않은 Microsoft의 SQL Server용 공식 Python 드라이버인 mssql-python을 사용하는 것이 좋습니다.

동기화 트리거 실패

오류 Sync triggers failed는 몇 가지 문제로 인해 발생할 수 있습니다. App Service 플랜에서 함수를 실행할 때, 사용자가 정의한 종속성과 Python 기본 제공 모듈이 서로 충돌하는 것이 한 가지 원인일 수 있습니다. 자세한 내용은 패키지 관리를 참조하세요.

문제 해결: 파일 또는 어셈블리를 로드할 수 없음

v2 프로그래밍 모델을 기반으로 로컬 환경에서 실행하는 과정에서 해당 오류가 발생할 수 있습니다. 이 오류는 예정된 릴리스에서 해결될 예정인 알려진 문제에서 비롯되었습니다.

다음은 이 오류에 대한 예 메시지입니다.

DurableTask.Netherite.AzureFunctions: 파일 또는 어셈블리 'Microsoft.Azure.WebJobs.Extensions.DurableTask, Version=2.0.0.0, Culture=neutral, PublicKeyToken=014045d636e89289'를 로드할 수 없음
시스템은 지정된 파일을 찾을 수 없습니다.

확장 번들의 캐싱 방식에 문제가 있어 오류가 발생하고 있습니다. 문제 해결을 위해서는 --verbose 를 사용해 해당 명령을 실행하고, 상세 정보를 확인하시기 바랍니다.

func host start --verbose

Loading startup extension <> 다음에 Loaded extension <>과 같은 로그에 확장 로드가 기록되어 있다면, 이는 캐싱 문제로 인해 발생했을 가능성이 큽니다.

이 문제를 해결하려면 다음을 수행합니다.

  1. 다음을 실행하여 .azure-functions-core-tools 경로를 찾습니다.

    func GetExtensionBundlePath

  2. .azure-functions-core-tools 디렉터리를 삭제합니다.

    rm -r <insert path>/.azure-functions-core-tools

Core Tools를 재실행하면 캐시 디렉터리가 자동으로 재생성됩니다.

문제 해결: Azure Storage 연결을 확인할 수 없습니다

이 오류는 로컬 출력에서 다음 메시지로 표시될 수 있습니다.

"Microsoft.Azure.WebJobs.Extensions.DurableTask: 'Storage'라는 Azure Storage 연결을 확인할 수 없습니다.
값은 Null일 수 없습니다. (공급자 매개 변수)

이 오류는 번들에서 로컬로 확장을 로드하는 방식의 결과입니다. 이 오류를 해결하려면 다음 작업 중 하나를 수행합니다.

  • Azurite와 같은 스토리지 에뮬레이터를 사용합니다. 함수 애플리케이션에서 스토리지 계정을 사용하지 않을 계획이라면 이 옵션이 유용합니다.

  • 스토리지 계정을 만들고 AzureWebJobsStorage 파일의 localsettings.json 환경 변수에 연결 문자열을 추가합니다. 스토리지 계정 트리거나 애플리케이션 바인딩을 활용하거나, 이미 생성된 스토리지 계정을 보유하고 있다면 이 옵션을 선택하세요. 시작하려면 스토리지 계정 만들기를 참조하세요.

배포 후 Functions을 찾을 수 없음

배포 후 호스트에서 Python 함수를 인식하지 못하게 하는 일반적인 빌드 문제들이 몇 가지 있습니다.

  • 패키지를 빌드 과정에서 정상적으로 복원하기 위해서는 에이전트 풀이 Ubuntu 환경에서 구동되어야 합니다. 배포 템플릿에서 빌드 및 배포를 수행하기 위해 Ubuntu 환경이 필요한지 확인합니다.

  • 함수 앱이 원본 저장소의 루트 경로에 위치하지 않는다면, 단계 pip install 에서 .python_packages 폴더를 생성할 때 올바른 경로를 참조하고 있는지 반드시 확인하시기 바랍니다. 다음 명령 예시에서 보듯이, 이 위치는 대문자와 소문자를 구분합니다.

    pip install --target="./FunctionApp1/.python_packages/lib/site-packages" -r ./FunctionApp1/requirements.txt

  • 템플릿을 통해 /home/site/wwwroot에 배포할 수 있는 패키지를 생성할 수 있어야 합니다. Azure Pipelines에서는 ArchiveFiles 작업을 통해 이 작업이 수행됩니다.

Azure Portal의 개발 문제

Azure Portal을 사용할 때 다음과 같은 알려진 문제와 해결 방법을 고려합니다.

  • 포털 내에서 함수 코드를 작성할 때 적용되는 몇 가지 일반적인 제한 사항이 있습니다. 자세한 내용은 Azure Portal의 개발 제한을 참조하세요.
  • 포털의 함수 앱에서 함수를 삭제하려면 함수 코드가 포함된 파일에서 해당 코드를 직접 제거해야 합니다. Python v2 프로그래밍 모델을 사용할 때는 삭제 버튼이 함수 제거 기능을 수행하지 못합니다.
  • 포털에서 함수를 생성할 경우, 개발 환경으로는 별도의 도구 사용을 권장받을 수 있습니다. 포털에서 코드를 편집할 수 없는 여러 상황이 있으며, 그 중에는 구문 오류가 감지되는 경우도 포함됩니다. 이러한 시나리오에서는 Visual Studio Code 또는 Azure Functions Core Tools를 사용하여 Functions 코드를 개발하고 게시합니다.

다음 단계

문제 해결에 어려움을 겪으시면 Azure Functions 팀으로 연락 주시기 바랍니다.

해결되지 않은 문제 보고

  • Last updated on