{"id":7215,"library":"fastapi-health","title":"FastAPI Health","description":"FastAPI Health is a Python library that provides a straightforward way to implement health check endpoints in FastAPI applications. It is currently at version 0.4.0 and offers dynamic health checks using custom conditions (callables) and handlers. The library is actively maintained with recent updates focusing on flexibility and dependency handling.","status":"active","version":"0.4.0","language":"en","source_language":"en","source_url":"https://github.com/Kludex/fastapi-health","tags":["fastapi","healthcheck","monitoring","api"],"install":[{"cmd":"pip install fastapi-health","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core dependency for building web APIs. `fastapi-health` extends its functionality.","package":"fastapi","optional":false}],"imports":[{"symbol":"health","correct":"from fastapi_health import health"},{"note":"The `HealthRoute` class was deprecated in version 0.2.0 in favor of the `health()` function, which provides a more flexible and functional approach to defining health checks.","wrong":"from fastapi_health import HealthRoute","symbol":"HealthRoute","correct":"This class is deprecated and should not be used."}],"quickstart":{"code":"from fastapi import FastAPI, Depends\nfrom fastapi_health import health\nimport os\n\napp = FastAPI()\n\ndef get_database_status():\n    # Simulate a database check\n    db_conn_string = os.environ.get('DATABASE_URL', 'sqlite:///./test.db')\n    # In a real app, this would attempt a connection or query\n    is_connected = db_conn_string is not None # Simplified check\n    return {\"database\": \"online\" if is_connected else \"offline\"}\n\ndef get_cache_status():\n    # Simulate a cache check\n    cache_host = os.environ.get('REDIS_HOST', 'localhost')\n    is_reachable = cache_host == 'localhost' # Simplified check\n    return is_reachable # Returns a boolean\n\n# Register the health endpoint with multiple conditions\napp.add_api_route(\"/health\", health([\n    get_database_status,\n    get_cache_status\n]))\n\n# To run this example, save it as main.py and run: uvicorn main:app --reload\n# Then navigate to http://localhost:8000/health","lang":"python","description":"This quickstart demonstrates how to set up a basic health check endpoint using `fastapi-health`. It includes two simulated condition checks: one returning a dictionary for detailed status and another returning a boolean. The `health()` function dynamically creates a route that aggregates the results of these conditions."},"warnings":[{"fix":"Replace `HealthRoute` usage with `app.add_api_route(\"/health\", health([your_condition_callable]))`. See quickstart for example.","message":"The `HealthRoute` class was removed/deprecated in version 0.2.0. Users on older versions upgrading to 0.2.0 or newer must migrate to using the `health()` function.","severity":"breaking","affected_versions":">=0.2.0"},{"fix":"Be mindful of expected HTTP status codes. If you need a `200` status with some components failing, consider custom `success_handler` and `failure_handler` or ensure all conditions return dictionaries where failure states are explicitly noted within the dictionary, or handle status codes explicitly using `success_status` and `failure_status` parameters.","message":"When using a mix of conditions that return `bool` and `dict`, if any condition returns `False`, the overall response status will default to `503` (Service Unavailable), even if other conditions return detailed 'online' dictionaries. The JSON body will still contain the results from all conditions.","severity":"gotcha","affected_versions":">=0.2.0"},{"fix":"Ensure that any I/O-bound health checks are `async def` functions and use `await` for their operations. If a synchronous library must be used, wrap it with `run_in_threadpool` or `asyncio.to_thread` to execute it in a separate thread.","message":"Performing synchronous I/O operations (e.g., blocking database calls, network requests) directly within `health` condition callables can block FastAPI's event loop, degrading performance and responsiveness for all other API endpoints.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Update your code to use the `health()` function instead: `from fastapi_health import health`, and then `app.add_api_route(\"/health\", health([your_condition_callable]))`.","cause":"Attempting to import or use the `HealthRoute` class after upgrading to `fastapi-health` version 0.2.0 or later, where it was removed/deprecated.","error":"NameError: name 'HealthRoute' is not defined"},{"fix":"Ensure all items in the `conditions` list passed to `health()` are actual callable functions, not their return values. For example, use `health([check_db_status])` instead of `health([check_db_status()])`.","cause":"Passing a boolean value directly to the `conditions` list instead of a callable (function) that returns a boolean or dictionary.","error":"TypeError: 'bool' object is not callable"},{"fix":"If all services are critical, accept the `503`. If partial failures should yield a `200` with detailed info, ensure all conditions return dictionaries, or implement custom `success_handler` and `failure_handler` to control the status code and response body more precisely. Alternatively, set `failure_status=200` if you always want a 200 response.","cause":"This often happens when `conditions` list contains a mix of callables where at least one returns `False` (boolean) while others return dictionaries indicating 'online' status. The presence of any `False` condition defaults the HTTP status to `503`.","error":"Status code 503 instead of 200, even when some services are reported as 'online' in the health check response."}]}