Azure Functions Doctor

Part of the Azure Functions Python DX Toolkit — dogfood-tested by azure-functions-cookbook-python.

Read this in: 한국어 | 日本語 | 简体中文

Azure Functions Doctor is the pre-deploy health gate for Azure Functions Python v2 projects — a diagnostic CLI that catches configuration issues, missing dependencies, and environment problems before they cause runtime failures in production.

Looking for the official azure-functions-skills doctor? This is an independent, offline, deterministic Python package — see how it compares and when to use each.

Part of the Azure Functions Python DX Toolkit → Bring FastAPI-like developer experience to Azure Functions

Why this exists

Deploying a broken Azure Functions app is expensive — the worker starts, the host reads config, and only then does it surface the issue in a production log. Common problems that slip through:

• Missing dependencies — azure-functions not in requirements.txt, discovered only at cold start
• Invalid configuration — host.json misconfigured, extensionBundle missing or outdated
• Runtime incompatibilities — Python version mismatch with Azure Functions runtime
• Silent failures — no virtual environment, Core Tools not installed, Application Insights key missing

azure-functions-doctor moves that failure left — catch it locally or in CI, not in production.

What it does

• 41 diagnostic checks — Python version, dependencies, host.json, Core Tools, Durable Functions, and more
• Multiple output formats — table, JSON, SARIF, JUnit for CI integration
• Profile support — minimal, deploy, development, or full rulesets depending on your needs
• Official GitHub Action — yeongseon/azure-functions-doctor@v1 for CI gates

Scope

This repository targets the decorator-based Azure Functions Python v2 programming model only. Non-v2 repositories are detected up front and reported as unsupported instead of running v2-only checks.

• Supported model: func.FunctionApp() with decorators such as @app.route()
• Unsupported model: legacy function.json-based Python v1 projects

Use azure-functions-doctor as part of a pre-deployment checklist alongside azure-functions-logging for observability.

What this package does not do

This package does not own:

• Fixing issues — it diagnoses configuration problems but does not auto-fix them
• API documentation — use azure-functions-openapi for API documentation and spec generation
• Request validation — use azure-functions-validation for request/response validation and serialization

Installation

From PyPI:

pip install azure-functions-doctor

From source:

git clone https://github.com/yeongseon/azure-functions-doctor-python.git
cd azure-functions-doctor-python
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

Quick Start

3 minutes, install to first fixed finding. Clone this repo (for the demo fixture), install, run the doctor on a project that ships a real deploy-risk bug, then fix what it points at:

pip install azure-functions-doctor
git clone https://github.com/yeongseon/azure-functions-doctor-python.git
cd azure-functions-doctor-python

# 1) Run the doctor on a broken fixture (dev-storage emulator leaked into infra)
azure-functions-doctor doctor --path examples/v2/broken-dev-storage-leak

# 2) Read the finding — it names the file, the risk, and the fix:
#    Dev-storage emulator connection in deployable config (ships to production):
#    - main.bicep
#    Fix: provision a real storage account connection ...

# 3) Fix it: point AzureWebJobsStorage at a real storage account in main.bicep,
#    keep UseDevelopmentStorage=true only in local.settings.json. Re-run:
#    the warning is gone; the exit code remains 0 because this check is optional.

Exit codes make it a CI gate: 0 when required checks pass, 1 on any required failure; optional findings warn without gating (--profile selects minimal / deploy / development / full, details).

Run the doctor in the current project:

azure-functions-doctor doctor

Run against a specific project:

azure-functions-doctor doctor --path ./examples/v2/http-trigger

Use a required-only profile:

azure-functions-doctor doctor --profile minimal

Output JSON for CI:

azure-functions-doctor doctor --format json

Agent-friendly findings

Agents can consume the same deterministic Finding Contract v2 JSON emitted by the CLI; the adapter adds no compatibility analysis or LLM judgment:

from pathlib import Path

from azure_functions_doctor.agent import explain_failures, load_agent_report

report = load_agent_report(Path("doctor.json"), sarif_path=Path("doctor.sarif"))
for finding in explain_failures(report):
    print(finding.rule_id, finding.evidence, finding.expected, finding.actual)
    print(finding.source_url, finding.last_verified)

Generate the existing artifacts before loading them:

azure-functions-doctor doctor --format json --output doctor.json
azure-functions-doctor doctor --format sarif --output doctor.sarif

The adapter rejects pre-v2 reports and findings whose analysis.type is not deterministic. It deliberately does not add rules, rank remediation, or infer compatibility.

Pin the Azure Functions target runtime explicitly:

azure-functions-doctor doctor --target-python 3.12

Use --target-python when the Python running azure-functions-doctor is not the same as the Python version your Function App will run on Azure. Python 3.10 remains accepted for analysis and is scheduled to reach Azure Functions end of support in October 2026; Python 3.14 is GA. Linux Consumption supports up to Python 3.12.

Project configuration (pyproject.toml)

For per-project defaults, add a [tool.azure-functions-doctor] table to your pyproject.toml. This is a deliberately minimal surface for suppressing rules and scoping the scan:

[tool.azure-functions-doctor]
# Rule ids to suppress. Suppressed rules are reported with the `skip`
# status (never silently passed).
ignore = ["check_application_insights", "check_core_tools"]

# Extra path globs to exclude from scans, layered on top of the built-in
# excluded directories (`.venv`, `node_modules`, `build`, ...). Globs are
# matched against each path relative to the project root.
exclude = ["legacy", "vendor/*.py"]

Precedence. CLI flags take precedence over configuration: --profile and --rules select the ruleset, and the config ignore/exclude then layer on top of the resolved run. Ignored rules that survive profile filtering are reported as skip rather than executed. There is no CLI equivalent for ignore/exclude in this minimal surface.

Command name and deprecated aliases

azure-functions-doctor is the canonical command. Two legacy console-script aliases still work but are deprecated and print a warning when invoked:

Migrate any scripts or CI pipelines to azure-functions-doctor before the v1.0.0 release removes the aliases.

See the deprecated aliases migration guide for step-by-step examples covering shell scripts, GitHub Actions, Makefiles, and pre-commit hooks.

Sample output (excerpt)

azure-functions-doctor doctor --path ./examples/v2/http-trigger

Azure Functions Doctor
Path: ./examples/v2/http-trigger

Programming Model
[✓] Programming model v2: Keyword '@app.|@bp.' found in source code (AST)

Python Env
[✓] Python version: Target Python: 3.12 (.python-version, >=3.10) — Tool runtime: 3.11.14
[✓] requirements.txt: requirements.txt exists
[✓] azure-functions package: Package 'azure-functions' declared in requirements.txt

Project Structure
[✓] host.json: host.json exists
[✓] host.json version: host.json version is "2.0"

Tooling
[✓] Azure Functions Core Tools (func): func detected

...

Doctor summary:
  0 fails, 5 warnings, 15 passed
Exit code: 0

The same command runs in CI pipelines — see CI Integration below and docs/deployment.md for details.

CI Integration

Recipe — gate a PR job on the deploy profile (exit 1 only on required failures; optional findings warn in the log):

- name: Pre-deploy health gate
  run: |
    pip install "azure-functions-doctor>=0.20,<1"
    azure-functions-doctor doctor --path . --profile deploy --format junit --output doctor.xml

Recipe — official GitHub Action with Code Scanning (see docs/examples/ci_integration.md for the full set: Azure DevOps, pre-commit, VS Code, and a minimal SARIF recipe):

- uses: yeongseon/azure-functions-doctor@v1
  with:
    path: .
    profile: deploy
    format: sarif
    output: doctor.sarif
    upload-sarif: true

GitHub Actions (CLI)

- name: Run azure-functions-doctor
  run: |
    pip install azure-functions-doctor
    azure-functions-doctor doctor --profile minimal --format json --output doctor.json

- name: Upload report
  if: always()
  uses: actions/upload-artifact@v4
  with:
    name: doctor-report
    path: doctor.json

Official GitHub Action

GitHub Marketplace

The Action is ready for publication as Azure Functions Doctor. Until its Marketplace listing is published, use the repository reference directly. The moving v1 ref follows each GitHub release, while a full release tag provides an immutable pin for stricter supply-chain policies.

• Recommended major ref: yeongseon/azure-functions-doctor@v1
• Immutable release ref: yeongseon/azure-functions-doctor@v0.23.0
• Source and support: azure-functions-doctor-python

- uses: yeongseon/azure-functions-doctor@v1
  with:
    path: .
    profile: minimal
    format: sarif
    output: doctor.sarif
    upload-sarif: "true"

Inputs

Outputs

Assign an id to the Action step to consume its outputs in later steps:

- name: Run azure-functions-doctor
  id: doctor
  continue-on-error: true
  uses: yeongseon/azure-functions-doctor@v1
  with:
    path: .
    profile: deploy

- name: Stop when diagnostics failed
  if: steps.doctor.outputs.failed-count != '0'
  run: exit 1

See docs/examples/ci_integration.md for Azure DevOps, pre-commit, VS Code, and SARIF upload examples — including a minimal copy-paste SARIF → GitHub code scanning recipe.

Demo

The demo below is generated from demo/doctor-demo.tape with VHS. It runs the real azure-functions-doctor doctor CLI against the representative example and then against an intentionally broken copy to show the pass/fail contrast.

The final terminal state is also captured as a static image for quick inspection.

Default ruleset

The default ruleset includes checks for:

• Azure Functions Python v2 decorator usage
• Python version
• virtual environment activation
• Python executable availability
• requirements.txt
• azure-functions dependency declaration
• host.json
• local.settings.json (optional)
• Azure Functions Core Tools presence and version (optional)
• Durable Functions host configuration (optional)
• Application Insights configuration (optional)
• extensionBundle configuration (optional)
• ASGI/WSGI callable exposure (optional)
• common unwanted files in the project tree (optional)

Examples

Requirements

• Python 3.11+
• Hatch for development workflows
• Azure Functions Core Tools v4+ recommended for local runs

When to use

• Before deploying an Azure Functions app (local pre-flight check)
• In CI/CD pipelines as a deployment gate
• When onboarding a new developer to catch environment setup issues
• After upgrading Python version or Azure Functions runtime
• As a pre-commit hook for configuration validation

How It Works

azure-functions-doctor doctor loads a JSON ruleset, dispatches each rule to a type-based handler, and aggregates the results into per-section output:

flowchart LR
    CLI["cli.py<br/>Typer CLI"] --> DOC["doctor.py<br/>Diagnostic runner"]
    DOC --> RULES[("assets/<br/>Rule inventory")]
    DOC --> HDLR["handlers/registry.py<br/>Type-based dispatch"]
    HDLR --> TR["target_resolver.py<br/>Version resolution"]
    DOC --> RES["SectionResult<br/>+ CheckResult"]
    RES --> OUT["table / json<br/>sarif / junit"]

See docs/architecture.md for the full component and sequence diagrams, and docs/diagnostics.md for the rule-evaluation pipeline.

Documentation

• docs/index.md
• docs/usage.md
• docs/rules.md
• docs/diagnostics.md
• docs/development.md
• docs/examples/ci_integration.md

Ecosystem

This package is part of the Azure Functions Python DX Toolkit.

Design principle: azure-functions-doctor owns pre-deploy diagnostics. It does not fix issues or generate code — it surfaces actionable findings so developers can fix them. Runtime behavior belongs to azure-functions-openapi (API documentation and spec generation), azure-functions-validation (request/response validation), and azure-functions-langgraph (LangGraph runtime exposure).

For AI Coding Assistants

This repository includes llms.txt and llms-full.txt for LLM-friendly documentation:

• llms.txt — Concise index of package info, CLI commands, quick start, and ecosystem overview
• llms-full.txt — Comprehensive API reference with output formats, diagnostic rules, custom rules, and CI integration patterns

When working with this codebase, LLM assistants should:

1. Use llms.txt for quick reference — the canonical package version (0.23.0), Python requirements (>=3.11,<3.15), CLI entry points
2. Refer to llms-full.txt for implementation details — output contracts, rule structure, custom rule patterns, handler types
3. Check src/azure_functions_doctor/cli.py — authoritative source for CLI options and validation
4. Review src/azure_functions_doctor/assets/rules/v2.json — complete ruleset with check definitions
5. Consult src/azure_functions_doctor/handlers/registry.py — diagnostic rule handlers and pattern matchers (handlers/_helpers.py for shared primitives)

For bug reports, feature requests, or documentation improvements, please open an issue or pull request on GitHub.

Disclaimer

This project is an independent community project and is not affiliated with, endorsed by, or maintained by Microsoft.

Azure and Azure Functions are trademarks of Microsoft Corporation.

License

MIT