diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index ddfd6fcf5e..7556f78ea8 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -34,9 +34,9 @@ and then you can find the java agent artifact at
 
 `javaagent/build/libs/opentelemetry-javaagent-<version>-all.jar`.
 
-### IntelliJ setup
+### IntelliJ setup and troubleshooting
 
-See [IntelliJ setup](docs/contributing/intellij-setup.md)
+See [IntelliJ setup and troubleshooting](docs/contributing/intellij-setup-and-troubleshooting.md)
 
 ### Style guide
 
diff --git a/docs/contributing/intellij-setup.md b/docs/contributing/intellij-setup-and-troubleshooting.md
similarity index 60%
rename from docs/contributing/intellij-setup.md
rename to docs/contributing/intellij-setup-and-troubleshooting.md
index 14192318d7..45c4b0102d 100644
--- a/docs/contributing/intellij-setup.md
+++ b/docs/contributing/intellij-setup-and-troubleshooting.md
@@ -1,4 +1,4 @@
-# IntelliJ setup
+# IntelliJ setup and troubleshooting
 
 **NB!** Please ensure that Intellij uses the same java installation as you do for building this
 project from command line. This ensures that Gradle task avoidance and build cache work properly and
@@ -26,3 +26,22 @@ Installation:
 Configuration:
 
 ![Recommended Settings](save-actions.png)
+
+## Troubleshooting
+
+Occassionally, Intellij gets confused, maybe due to the number of modules in this project,
+maybe due ot other reasons. In any case, here's some things that might help:
+
+### Invalidate Caches > "Just restart"
+
+* Go to File > Invalidate Caches...
+* Unselect all the options
+* Click the "Just restart" link
+
+This seems to fix more issues than just closing and re-opening Intellij :shrug:.
+
+### Delete your `.idea` directory
+
+* Close Intellij
+* Delete the `.idea` directory in the root directory of your local repository
+* Open Intellij