Troubleshooting#
Here are a few tips for avoiding and debugging some common problems.
General Tips#
Make sure you’re using the latest version:
pip install -U requests-cache
Try searching issues for similar problems
Enable debug logging to get more information
If you have a problem and figure it out yourself, it’s likely that someone else will have the same problem. It can be helpful to create an issue on GitHub just for reference, or submit a PR to add some notes to this page.
Logging#
Debug logging can be enabled with the standard python logging
module, for example with
logging.basicConfig()
:
import logging
logging.basicConfig(level='DEBUG')
For prettier, more readable logs, try the rich library’s logging handler:
import logging
from rich.logging import RichHandler
logging.basicConfig(
level='DEBUG', format="%(message)s", datefmt="[%X]", handlers=[RichHandler()]
)
If you have other libraries installed that have verbose debug logging, you can configure only the
loggers you want with logger.setLevel()
:
import logging
logging.basicConfig(level='WARNING')
logging.getLogger('requests_cache').setLevel('DEBUG')
Potential Issues#
Patching: See Patching Limitations & Potential Issues for notes specific to
install_cache()
Imports: It’s recommended to make all your imports from the top-level
requests_cache
package:from requests_cache import x
Cache settings: Some issues may be caused by changing settings for an existing cache. This is only likely to happen with some of the more advanced features like Custom Serializers and Custom Request Matching. In these cases, the easiest way to resolve the issue is to clear the cache with
CachedSession.cache.clear()
.Library updates: New releases of
requests
,urllib3
orrequests-cache
itself can potentially change response data, and be incompatible with previously cached responses. See issues #56 and #102.Note
A cached response that can’t be reused will simply be deleted and fetched again. If you get a traceback just by reading from the cache, this is not intended behavior, so please create a bug report!
Common Error Messages#
Here are some error messages you may see either in the logs or (more rarely) in a traceback:
Unable to deserialize response with key {cache key}
: This usually means that a response was previously cached in a format that isn’t compatible with the current version of requests-cache or one of its dependencies.Request for URL {url} failed; using cached response
: This is just a notification that the stale_if_error option is working as intended.RequestException
: These are general request errors not specific to requests-cache. Seerequests
documentation on Errors and Exceptions for more details.ModuleNotFoundError
:No module named 'requests_cache.core'
: This module was deprecated inv0.6
and removed inv0.8
. Please import fromrequests_cache
instead ofrequests_cache.core
.ImportError
: Indicates a missing required or optional dependency.If you see this at import time, it means that one or more required dependencies are not installed
If you see this at runtime or in a log message, it means that one or more optional dependencies are not installed
See Requirements for details
sqlite3.OperationalError
:unable to open database file
orIOError
: This usually indicates a file permissions or ownership issue with either the database file or its parent directory.sqlite3.OperationalError
:database is locked
: This indicates a concurrency issue, and likely a bug. requests-cache + SQLite is intended to be thread-safe and multiprocess-safe, so please create a bug report if you encounter this.ResourceWarning
:unclosed <ssl.SSLSocket ...>
: This warning can safely be ignored.This is normal behavior for
requests.Session
, which uses connection pooling for better performance. In other words, these connections are intentionally left open to reduce the number of round-trips required for consecutive requests. For more details, see the following issues:requests/#3912: ResourceWarning: unclosed socket.socket when I run a unittest?
requests/#2963: ResourceWarning still triggered when warnings enabled
If needed, this warning can be suppressed with:
import warnings warnings.simplefilter('ignore', ResourceWarning)
Bug Reports#
If you believe you’ve found a bug, or if you’re just having trouble getting requests-cache to work the way you want, please create an issue for it on GitHub.
Details that will help your issue get resolved:
A complete example to reproduce the issue
Tracebacks and logging output
Any other details about what you want to accomplish and how you want requests-cache to behave