Errors — oslo.cache — branch stable/2026.2
Branch
stable/2026.2@fc96999a99e4— repository https://opendev.org/openstack/oslo.cache — analysed on 2026-10-28
oslo.cache defines 2 exceptions (oslo_cache/exception.py:16-21). Neither has an HTTP status: they reach the calling service, which usually lets them become a 500 or fails at startup.
1. ConfigurationError: the configuration is refused
Raised when the region is configured, so in practice when the service starts (or at its first cache use). The messages recorded by _rewrite/config-mapping_stable-2026.2.json are:
| Situation | Message | Reference |
|---|---|---|
| The object passed is not a dogpile region | region not type dogpile.cache.CacheRegion | oslo_cache/core.py:478-481 |
backend_expiration_time < expiration_time | backend_expiration_time should not be smaller than expiration_time. | oslo_cache/core.py:241-245 |
backend_expiration_time with a backend other than memcached or Redis | Enabling backend expiration is not supported bythe %s driver (not formatted, see below) | oslo_cache/core.py:262-266 |
tls_enabled with a backend other than pymemcache, memcache_pool, Redis | TLS setting via [cache] tls_enabled is not supported by the <backend> backend. Set [cache] tls_enabled=False or use a different backend. | oslo_cache/core.py:316-321 |
enable_socket_keepalive with a backend other than pymemcache or Redis | Socket keepalive is not supported by the <backend> backend | oslo_cache/core.py:355-359 |
enable_retry_client with a backend other than pymemcache | Retry client is only supported by the 'dogpile.cache.pymemcache' backend. | oslo_cache/core.py:366-372 |
Redis sentinel not in host:port form | Malformed sentinel server format | oslo_cache/core.py:123-127 |
memcache_pool with memcache_sasl_enabled but no username or password | username and password should be configured to use SASL authentication. | oslo_cache/backends/memcache_pool.py:73-80 |
Two defects in these checks:
- Unformatted message: the backend name is passed as a second argument of the exception, not substituted.
str(e)shows a tuple, with the typobythe(oslo_cache/core.py:263-266). - **TLS impossible with
dogpile.cache.bmemcached**: the list of TLS-capable backends containsdogpile.cache.bmemcache, which does not exist (oslo_cache/core.py:270). The real namedogpile.cache.bmemcached, which is one of the 13 accepted choices, is therefore refused (case "error: tls_enabled with dogpile.cache.bmemcached" in_rewrite/config-mapping_stable-2026.2.json). TLS with python-binary-memcached remains possible throughoslo_cache.memcache_pool.
Other refusals that are not ConfigurationError:
ImportError("python-binary-memcached package is missing")when TLS or SASL is requested for memcache_pool without the library (oslo_cache/backends/memcache_pool.py:81-82);- the
backendvalue is checked by oslo.config (choices): an unknown backend fails when the option is read.
2. QueueEmpty: no memcached connection available
Unable to get a connection from pool id <id> after <seconds> seconds. (oslo_cache/_memcache_pool.py:183-193).
- Situation: the
memcache_pool_maxsizeclients (10) are all in use, and none is returned withinmemcache_pool_connection_get_timeout(10 s). Scenario 16 of 07 reproduces it with a pool of 1. - Propagation: it goes up through dogpile to the cached function: the service's request fails (typically 500), while an unreachable memcached does not cause an error (below).
3. Errors that are not raised
| Situation | Behaviour | Source |
|---|---|---|
| memcached unreachable (python-memcached, memcache_pool) | the client marks the server dead and returns "no value": cache miss, the function is computed, no exception and no log from oslo.cache (scenario 14) | python-memcached; oslo_cache/_memcache_pool.py:302-321 (dead mark shared by the pool for memcache_dead_retry) |
backend_argument without : | LOG.error("Unable to build cache config-key. Expected format \"<argname>:<value>\". Skipping unknown format: %s"), argument ignored | oslo_cache/core.py:142-150 |
| Pool connection that fails to close | LOG.warning("Unable to cleanup a connection: %s") | oslo_cache/_memcache_pool.py:137-140 |
dogpile.cache.memcached unreachable | same as memcache_pool: miss (scenario 15) | python-memcached |
dogpile.cache.pymemcache unreachable | **ConnectionRefusedError reaches the caller**; with enable_retry_client it becomes a miss (scenario 15) | pymemcache, oslo_cache/core.py:366-387 |
dogpile.cache.redis unreachable | **redis.exceptions.ConnectionError reaches the caller** (scenario 15) | redis-py |
Source: reverse-spec-oslo.cache/02-errors_stable-2026.2.md. The _rewrite/ and _inventory/ files are not published on the site.