Install & Compatibility
Where this runs
tested against v8.1.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.712s · 45.4MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 4.8s · import 0.690s · 46MB
49MB installed
● package 49MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
CORS
✓ from oslo_middleware import cors
✗ from oslo.middleware import cors
Top-level `oslo_middleware` package uses underscores, not dots, for direct imports.
CatchErrors
✓ from oslo_middleware import catch_errors
✗ from oslo.middleware import catch_errors
Middleware components are typically imported from their respective snake_case modules within `oslo_middleware`.
RequestId
✓ from oslo_middleware import request_id
✗ from openstack.common.middleware import request_id
Older OpenStack projects might have used `openstack.common.middleware`. All new code should use `oslo_middleware`.
This example demonstrates how to chain two `oslo_middleware` components, `RequestId` and `CatchErrors`, with a basic WSGI application. `RequestId` ensures a unique ID for each request, and `CatchErrors` provides high-level error handling, preventing raw tracebacks from being exposed to clients. This setup is typical in OpenStack services.
import webob.dec
import webob.exc
from oslo_middleware import catch_errors
from oslo_middleware import request_id
@webob.dec.wsgify
def simple_app(req):
if req.path_info == '/hello':
return f"Hello, Request ID: {req.environ.get('openstack.request_id', 'N/A')}"
elif req.path_info == '/error':
raise ValueError('Something went wrong!')
return webob.exc.HTTPNotFound()
# Order matters: RequestId first to ensure ID is generated,
# then CatchErrors to handle subsequent exceptions.
app = request_id.RequestId(simple_app)
app = catch_errors.CatchErrors(app)
# To run this with a WSGI server (e.g., Gunicorn or uWSGI):
# Save as app.py and run 'gunicorn app:app'
# Test with curl:
# curl http://127.0.0.1:8000/hello
# curl http://127.0.0.1:8000/error
Debug
Known issues
breakingImport paths for middleware components were standardized under the `oslo_middleware` namespace. Older projects might still reference `openstack.common.middleware`.fixUpdate import statements from `from openstack.common.middleware import X` to `from oslo_middleware import X` (or specific module, e.g., `from oslo_middleware import request_id`).
affects: < 1.0.0 (pre-Oslo graduation)
gotchaIncorrect middleware order can lead to unexpected behavior. For instance, `CatchErrors` should typically wrap your application and other middleware that might raise exceptions, while `RequestId` often comes early in the pipeline.fixCarefully consider the order of middleware in your WSGI pipeline. Middleware applied earlier will process requests first and responses last. For example, `RequestId` usually precedes error handling or authentication middleware.
affects: All versions
deprecatedThe `CatchErrors` middleware, in older versions, had an information-disclosure flaw (CVE-2017-2592) where sensitive values could be included in traceback error messages, potentially exposing tokens or other data.fixEnsure you are using a patched version of `oslo.middleware` (newer than the affected versions). Review and sanitize error messages and logs if you are using custom error handling or older versions.
affects: < 3.23.1, < 4.4.1 (specific to Red Hat OpenStack Platform Newton, but general warning applies)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'oslo.middleware'
The package name is `oslo-middleware` (with a hyphen) for installation, but the Python import path uses an underscore: `oslo_middleware`.
fixChange your import statement to `from oslo_middleware import ...`.
TypeError: 'module' object is not callable (when trying to use `oslo_middleware.CORS` directly)
Many `oslo_middleware` components are classes that need to be instantiated, or they provide a factory function (e.g., `CORS.factory()`) for `paste.deploy` integration, not directly callable as a module.
fixInstantiate the middleware class: `app = cors.CORS(your_app, ...)` or use its `factory` method if integrating with `paste.deploy`. Refer to specific middleware documentation for correct usage.
KeyError: 'openstack.request_id' (or similar env var not found)
Attempting to access a request environment variable (like `openstack.request_id`) that has not been set by its corresponding middleware.
fixEnsure the relevant middleware (e.g., `RequestId` for `openstack.request_id`) is properly included and ordered in your WSGI pipeline before your application attempts to access its values.
Upgrade
Version history
8.1.0latest on PyPI · released May 18, 2026
Audit
Dependencies
WebObrequiredCore dependency for WSGI request/response objects and decorators.
oslo.configoptionalUsed for configuration management within OpenStack projects.
oslo.contextoptionalProvides context management, often used for request IDs and user context.
oslo.i18noptionalFor internationalization support.
oslo.utilsoptionalCollection of utility functions used across Oslo projects.