1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
|
(debug)=
# {fas}`exclamation-circle` 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](https://github.com/requests-cache/requests-cache/issues?q=is%3Aissue+label%3Abug)
for similar problems
* Enable debug logging to get more information
* If you have a problem and [figure it out yourself](https://xkcd.com/979/), 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
{py:func}`logging.basicConfig`:
```python
import logging
logging.basicConfig(level='DEBUG')
```
For prettier, more readable logs, try the [rich](https://github.com/willmcgugan/rich) library's
[logging handler](https://rich.readthedocs.io/en/stable/logging.html):
```python
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()`:
```python
import logging
logging.basicConfig(level='WARNING')
logging.getLogger('requests_cache').setLevel('DEBUG')
```
## Potential Issues
* **Patching:** See {ref}`monkeypatch-issues` for notes specific to {py:func}`.install_cache`
* **Imports:** It's recommended to make all your imports from the top-level `requests_cache` package:
```python
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 {ref}`custom-serializers` and
{ref}`custom-matching`. In these cases, the easiest way to resolve the issue is to clear the cache
with {py:meth}`CachedSession.cache.clear() <.BaseCache.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](https://github.com/requests-cache/requests-cache/issues/56) and
[#102](https://github.com/requests-cache/requests-cache/issues/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 {py:meth}`~.BaseCache.remove` the invalid responses or {py:meth}`~.BaseCache.clear` the
entire cache.
* **`Request for URL {url} failed; using cached response`:** This is just a notification that the
{ref}`stale_if_error <request-errors>` option is working as intended.
* **{py:exc}`~requests.RequestException`:** These are general request errors not specific to
requests-cache. See `requests` documentation on
[Errors and Exceptions](https://2.python-requests.org/en/master/user/quickstart/#errors-and-exceptions)
for more details.
* **{py:exc}`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`.
* **{py:exc}`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 {ref}`requirements` for details
* **{py:exc}`sqlite3.OperationalError`: `unable to open database file`** or **{py:exc}`IOError`:**
This usually indicates a file permissions or ownership issue with either the database file or its parent directory.
* **{py:exc}`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.
* **{py:exc}`ResourceWarning`: `unclosed <ssl.SSLSocket ...>`:** This warning can **safely be ignored.**
* This is normal behavior for {py:class}`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？](https://github.com/psf/requests/issues/3912)
* [requests/#2963: ResourceWarning still triggered when warnings enabled](https://github.com/psf/requests/issues/2963#issuecomment-169631513)
* [requests-cache/#413](https://github.com/requests-cache/requests-cache/issues/413)
* If needed, this warning can be suppressed with:
```python
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](https://github.com/requests-cache/requests-cache/issues/new/choose) 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
|
