Add health check to Ragflow instance

[alspires]

Hello all,

I've read around about this and I know that there's no built-in endpoint/funccionality on Ragflow to run health checks and see if the application is still accessible, so I'm making this post to know if anyone's ever needed to do something similar and how.

Would you mind sharing available approaches, please?

TIA.

[dosubot[bot]]

Ragflow doesn't have a built-in public health check endpoint, but its API is built on Flask and is highly extensible. There is a /status endpoint that checks the health of core dependencies (Elasticsearch, storage, database, Redis), but it's protected by authentication and not accessible without logging in (source).

If you want a public health check endpoint, you can easily add one by creating a new *_app.py file in api/apps/ with a Flask Blueprint and a simple route (for example, /healthz) that returns a 200 OK. The Ragflow server will auto-register it on startup thanks to its dynamic blueprint loader (source).

A minimal example:

# api/apps/health_app.py
from flask import Blueprint, jsonify

manager = Blueprint("health", __name__)

@manager.route("/healthz", methods=["GET"])
def health_check():
    return jsonify({"status": "ok"}), 200

This will expose /healthz without authentication. For more advanced checks, you can reuse the logic from /status or add custom checks as needed. For best practices, keep the health endpoint lightweight, avoid exposing sensitive info, and consider rate limiting if it's public.

The modular Flask/Blueprint setup makes it straightforward to customize or extend endpoints as your needs evolve.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[dosubot[bot]]

No, Ragflow endpoints—including /status and all the typical listing endpoints—do not return error HTTP status codes (like 500 or 503) when a dependency such as PostgreSQL is broken. Instead, they always respond with HTTP 200, even if a backend service is down. Any errors (like a failed database connection) are reported inside the JSON response body, usually with a status field set to "red" or an error message, but the HTTP status code remains 200. This is by design and applies to both health/status endpoints and resource listing endpoints. If you need an endpoint that returns a non-200 status code when a dependency is down, you’d need to implement custom logic for that—let me know if you want a code example or guidance on how to do it.
Reference: /status implementation

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[alspires]

@dosu taking this last piece of info into consideration, if I wanted to define if the application is healthy or not based on the response from a listing endpoint, for example, would I have to parse and go through the error message or does the code attribute already tells me there's a problem? I noticed I was getting "code: 100" when calling datasets endpoint with invalid psql credentials.

[dosubot[bot]]

You don't need to parse the error message—just check the code attribute in the response. For Ragflow listing endpoints, code: 0 always means success and a healthy backend. Any non-zero code (like 100, which stands for EXCEPTION_ERROR) reliably signals a problem, including broken dependencies such as invalid database credentials. This convention is consistent across all listing endpoints, so your health check logic can simply look for code == 0 to confirm health, and treat any other value as an error state. You can see the code definitions in the RetCode enum and the error handling in the datasets endpoint.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[alspires]

@dosu can you tell me more about self-hosted instances, please? I need to make a call to the API that is in the same container, and having to generate an API key in order to be authorized to do so would not be a very good approach.

[dosubot[bot]]

In Ragflow, "self-hosted" mode usually refers to running the MCP server for a single tenant, where you provide an API key at launch. In this mode, the MCP server itself uses the API key internally, but it does not require every client request to include an Authorization header. So, if you're interacting with the MCP server in self-host mode, you can make internal API calls (even from within the same container) without generating or passing an API key per request—authentication is not enforced at the HTTP layer for each call in this mode (reference).

However, if you're calling the core Ragflow API server directly (not via the MCP server), authentication is always enforced for protected endpoints, regardless of whether the call is internal or external. There is no built-in bypass for localhost or same-container requests; you must provide an API key or session token for those endpoints (reference).

So, for internal automation or probes, use the MCP server in self-host mode if you want to avoid per-request API keys. If you need to call the core API server directly, an API key or session token is always required.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[ZhenhangTung]

Hi! Appreciate your feedback! Could you open a feature request? Could be implemented later, especially after our SaaS launch.

[alspires]

@ZhenhangTung created: #10106