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 or requests-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.

  • This message is to help with debugging and can generally be ignored. If you prefer, you can either remove() the invalid responses or clear() the entire cache.

• 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. See requests documentation on Errors and Exceptions for more details.

• ModuleNotFoundError: No module named 'requests_cache.core': This module was deprecated in v0.6 and removed in v0.8. Please import from requests_cache instead of requests_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 or IOError: 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

  • requests-cache/#413

  • 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