From 45d18dcd4653f56e9fdaf438a5897882c44fc13a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Melissa=20Weber=20Mendon=C3=A7a?= <melissawm@gmail.com>
Date: Tue, 31 Dec 2024 12:26:10 -0300
Subject: [PATCH] Add troubleshooting page (#533)

# References and relevant issues
Closes #40, #493

# Description
Adds a troubleshooting page under Usage. Not complete by any means, but
a starting point. It has two sections, one for known issues and another
for an FAQ.

---------

Co-authored-by: Peter Sobolewski <76622105+psobolewskiPhD@users.noreply.github.com>
---
 docs/_toc.yml               |  1 +
 docs/howtos/layers/image.md |  1 +
 docs/troubleshooting.md     | 46 +++++++++++++++++++++++++++++++++++++
 3 files changed, 48 insertions(+)
 create mode 100644 docs/troubleshooting.md

diff --git a/docs/_toc.yml b/docs/_toc.yml
index 7487f445..837e63b1 100644
--- a/docs/_toc.yml
+++ b/docs/_toc.yml
@@ -74,6 +74,7 @@ subtrees:
       - file: further-resources/glossary
       - file: further-resources/napari-workshops
       - file: further-resources/sample_data
+      - file: troubleshooting
       - file: gallery
       - file: release/index
         subtrees:
diff --git a/docs/howtos/layers/image.md b/docs/howtos/layers/image.md
index ffc43cc9..41c6c38d 100644
--- a/docs/howtos/layers/image.md
+++ b/docs/howtos/layers/image.md
@@ -349,6 +349,7 @@ we had passed only the colormap it would have been given a default name.
 The named colormap now appears in the dropdown alongside a thumbnail of the full
 range of the colormap.
 
+(contrast-limits)=
 ## Adjusting contrast limits
 
 Each image layer gets mapped through its colormap according to values called
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
new file mode 100644
index 00000000..a0aac418
--- /dev/null
+++ b/docs/troubleshooting.md
@@ -0,0 +1,46 @@
+# Troubleshooting
+
+This page collects a few known issues and solutions for common problems that users might encounter when using napari.
+If you are facing an error that is not covered by this page, please check existing issues on the
+[napari repository](https://github.com/napari/napari/issues). If you can't find what you are looking for, 
+please open a new issue.
+
+## Known issues
+
+### Resetting preferences and settings
+
+Changing napari versions—updating or downgrading—within an environment can cause issues with settings.  These issues can
+manifest as napari failing to start. 
+
+Likewise, issues with napari on multiple monitors or with window sizes are also due to settings. These issues can
+frequently be solved by resetting the settings back to default using the terminal command:
+
+```python
+napari --reset
+```
+
+### torch + rosetta + napari crashes Python
+
+In some cases, when using napari on Mac M1 using Rosetta you may experience crashing when adding layers or using a script.
+If you observe this, you should run napari using the native arm64 Python interpreter (see [napari#7259](https://github.com/napari/napari/issues/7259).
+
+### "module napari has no attribute Viewer"
+
+This may happen when doing an editable install on top of a normal one, or when you have a local file called `napari.py`.
+
+To fix this, either rename the file or remove all previous napari versions in your environment before installing the editable version.
+
+### My image renders as all black/all white
+
+This can happen when the contrast limits are not set correctly. You can reset the contrast limits by right-clicking
+"contrast limits", then clicking the "Reset" button in the advanced contrast limits widget shown.
+
+See [](contrast-limits) for more information on contrast limits.
+
+### PermissionError when trying to launch napari on Windows
+
+If you have a PermissionError when trying to launch napari on Windows, it could be due to how numba deals with
+permissions. Try setting `NUMBA_CACHE_DIR` to an user-accessible location.
+
+See [napari#7288](https://github.com/napari/napari/issues/7288).
+