Flask Request ID Header

Common errors

• ModuleNotFoundError: No module named 'flask_request_id_header.middleware'

  cause The `flask-request-id-header` package is not installed in the current environment, or the import path `from flask_request_id_header.middleware import RequestID` is incorrect.
  fix Ensure the package is installed: `pip install flask-request-id-header`. Verify the import statement matches the correct path.

• KeyError: 'X-Request-ID' when accessing `request.headers['X-Request-ID']`

  cause Attempting to access the `X-Request-ID` header from the Flask `request` object outside of an active request context (e.g., during application setup) or before the middleware has processed the request. While the middleware ensures the header, access without a proper request context will fail.
  fix Access the header within a request context (e.g., inside a route function, a `before_request` handler, or using `app.test_request_context()`). Use `request.headers.get('X-Request-ID', 'default_value')` to safely retrieve the header without raising a `KeyError` if it might be missing in certain scenarios.

• AttributeError: 'Request' object has no attribute 'request_id' or NameError: name 'g' is not defined when trying to access `g.request_id`

  cause This specific library (flask-request-id-header) does not expose the request ID via `request.request_id` or `flask.g.request_id` by default. These patterns are common in *other* Flask request ID extensions.
  fix Access the request ID directly from the request headers dictionary: `request.headers.get('X-Request-ID')`.

Warnings

• deprecated The 'X-' prefix for custom HTTP headers, such as 'X-Request-ID', is technically deprecated by W3C standards, which recommend formal header naming conventions. While still widely supported and a de-facto standard, this might be a consideration for future-proofing.
  Fix: No direct fix needed for current functionality, but be aware of evolving HTTP header conventions.
• gotcha The middleware automatically appends a new UUID (version 4) to the 'X-Request-ID' header if an existing value does not already contain at least one UUID v4. If you wish to preserve a custom non-UUID request ID provided by a client, you must configure `app.config['REQUEST_ID_UNIQUE_VALUE_PREFIX']` with a prefix that your custom IDs will use.
  Fix: Set `app.config['REQUEST_ID_UNIQUE_VALUE_PREFIX'] = 'YOUR_PREFIX-'` to prevent modification of headers starting with 'YOUR_PREFIX-'.
• gotcha This library focuses on ensuring the 'X-Request-ID' header exists and is correctly formatted. It does not automatically integrate the request ID into Flask's default logging system. To include the request ID in your application logs, you will need to implement a custom logging filter or use a more comprehensive logging library.
  Fix: Manually configure a `logging.Filter` to inject `request.headers.get('X-Request-ID')` into log records.

Install

• pip install flask-request-id-header Install with pip

Imports

• RequestID

  from flask_request_id_header.middleware import RequestID

Quickstart

Initializes a Flask app and applies the RequestID middleware. It then defines a simple route to demonstrate how to retrieve the `X-Request-ID` header from the request.

from flask import Flask, request
from flask_request_id_header.middleware import RequestID

app = Flask(__name__)
RequestID(app)

@app.route('/')
def hello_world():
    request_id = request.headers.get('X-Request-ID', 'No-Request-ID-Found')
    return f'Hello, world! Request ID: {request_id}'

if __name__ == '__main__':
    app.run(debug=True)