Add some more troubleshooting info to docs

4 files changed, 64 insertions, 23 deletions

diff --git a/.github/ISSUE_TEMPLATE/bug.md b/.github/ISSUE_TEMPLATE/bug.md
index 343c972..5557290 100644
--- a/.github/ISSUE_TEMPLATE/bug.md
+++ b/.github/ISSUE_TEMPLATE/bug.md
@@ -6,6 +6,10 @@ labels: bug
 
 ---
 
+<!--
+Note: See the troubleshooting page for help with some common issues:
+https://requests-cache.readthedocs.io/en/latest/user_guide/troubleshooting.html
+-->
 ### The problem
 _A description of what the bug is, including a complete traceback (if applicable)_
 
@@ -19,6 +23,6 @@ _With a complete code example, if possible_
 _Is there an existing workaround for this issue?_
 
 ### Environment
-- requests-cache version: [e.g. `0.6.2` or `master`]
+- requests-cache version: [e.g. `0.8.1` or `master`]
 - Python version: [e.g. `3.9`]
 - Platform: [e.g. Debian 10]
diff --git a/docs/user_guide/expiration.md b/docs/user_guide/expiration.md
index 5892edd..0f9c62a 100644
--- a/docs/user_guide/expiration.md
+++ b/docs/user_guide/expiration.md
@@ -67,6 +67,7 @@ frequently, another that changes infrequently, and another that never changes. E
 - If there is more than one match, the first match will be used in the order they are defined
 - If no patterns match a request, `CachedSession.expire_after` will be used as a default
 
+(request-errors)=
 ## Expiration and Error Handling
 In some cases, you might cache a response, have it expire, but then encounter an error when
 retrieving a new response. If you would like to use expired response data in these cases, use the
diff --git a/docs/user_guide/installation.md b/docs/user_guide/installation.md
index 98dd2a0..174baf3 100644
--- a/docs/user_guide/installation.md
+++ b/docs/user_guide/installation.md
@@ -23,9 +23,10 @@ pip install --pre requests-cache
 See {ref}`contributing` for setup steps for local development
 :::
 
+(requirements)=
 ## Requirements
-You may need additional dependencies depending on which backend you want to use. To install with
-extra dependencies for all supported {ref}`backends`:
+You may need additional dependencies depending on which features you want to use. To install with
+extra dependencies for all supported {ref}`backends` and {ref}`serializers`:
 ```
 pip install requests-cache[all]
 ```
diff --git a/docs/user_guide/troubleshooting.md b/docs/user_guide/troubleshooting.md
index 10c8c86..25d4d3f 100644
--- a/docs/user_guide/troubleshooting.md
+++ b/docs/user_guide/troubleshooting.md
@@ -2,25 +2,14 @@
 # {fa}`exclamation-circle` Troubleshooting
 Here are a few tips for avoiding and debugging some common problems.
 
-## Potential Issues
-* **Patching:** See {ref}`monkeypatch-issues` for notes specific to {py:func}`.install_cache`
-* **Imports:** It's recommended to import everything from the top-level `requests_cache` package.
-  Other internal modules and utilities may change with future releases.
-* **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/reclosedev/requests-cache/issues/56) and
-  [#102](https://github.com/reclosedev/requests-cache/issues/102).
-* **Cache settings:** Some issues may be caused by changing settings for an existing cache. For
-  example, if you are using {ref}`custom-serializers`, {ref}`custom-matching`, or other advanced
-  features, you may get unexpected behavior if you change those settings and reuse previously cached
-  data. In these cases, the easiest way to resolve the issue is to clear the cache with
-  ({py:meth}`CachedSession.cache.clear() <.BaseCache.clear>`).
-
-```{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!
-```
+## General Tips
+* Make sure you're using the latest version: `pip install -U requests-cache`
+* Try [searching issues](https://github.com/reclosedev/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
@@ -51,6 +40,52 @@ 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/reclosedev/requests-cache/issues/56) and
+  [#102](https://github.com/reclosedev/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. It could also be the result of switching {ref}`serializers`.
+  * This message is to help with debugging and can generally be ignored. If you prefer, you can
+    either {py:meth}`~.BaseCache.clear` the cache or {py:meth}`~.BaseCache.remove_expired_responses`
+    to get rid of the invalid responses.
+* **`Request for URL {url} failed; using cached response`:** This is just a notification that the
+  {ref}`old_data_on_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}`ImportError`:**
+  * 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.
+
 ## 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
@@ -59,4 +94,4 @@ the way you want, please
 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 do and how you want it to work
+* Any other details about what you want to accomplish and how you want requests-cache to behave