Merge pull request #35 from ijsto:SA/Docs---init-troubleshooting

Merge pull request #34 from ijsto/changeset-release/main

.changeset/purple-flowers-fold.md

@@ -0,0 +1,5 @@
+---
+"keystone-6-oauth": patch
+---
+
+Initialize Troubleshooting

docs/docs/.vuepress/configs/sidebar/en.ts

@@ -26,6 +26,14 @@ export const en: SidebarConfig = {
         "/tutorials/posts.md",
       ],
     },
+    {
+      text: "Troubleshooting",
+      collapsible: false,
+      children: [
+        "/troubleshooting/known-errors.md",
+        "/troubleshooting/limitations.md",
+      ],
+    },
     {
       text: "Migration Guides",
       collapsible: true,
@@ -49,6 +57,31 @@ export const en: SidebarConfig = {
       children: ["/migrations/v20-v1.md"],
     },
   ],
+  "/troubleshooting/": [
+    {
+      text: "Tutorials",
+      collapsible: true,
+      children: [
+        "/tutorials/introduction.md",
+        "/tutorials/recipes.md",
+        "/tutorials/videos.md",
+        "/tutorials/posts.md",
+      ],
+    },
+    {
+      text: "Troubleshooting",
+      collapsible: false,
+      children: [
+        "/troubleshooting/known-errors.md",
+        "/troubleshooting/limitations.md",
+      ],
+    },
+    {
+      text: "Migration Guides",
+      collapsible: true,
+      children: ["/migrations/v20-v1.md"],
+    },
+  ],
   "/advanced/": [
     {
       text: "Advanced",

docs/docs/troubleshooting/known-errors.md

@@ -0,0 +1,50 @@
+# Known Errors
+
+Below is a list of potential errors or issues you may run into (that we have discovered).
+
+## 🚨 There was an error loading your Keystone config
+
+### Issue
+
+After installing, re-installing, cloning or starting your Keystone App, you are faced with the below error:
+
+```bash
+Error: Cannot find module '/home/optimbro/dev/projects/dotSentry/backend/.keystone/admin/.next/server/pages/api/__keystone_api_build'
+```
+
+### Solution
+
+#### **Option A**
+
+- delete the `.keystone` and `node_modules` folders
+- re-install Keystone `yarn install`
+- start Keystone `yarn dev`
+
+Additionally you can visit http://localhost:3000/admin/api/auth (`http://BACKEND_URL/admin/api/auth`) and log in.
+This should explicitly generate the missing `api` folder.
+
+#### **Option B**
+
+- delete the `.keystone` and `node_modules` folders
+- clean yarn cache `yarn cache clean`
+- re-install Keystone `yarn install`
+- start Keystone `yarn dev`
+
+Additionally you can visit http://localhost:3000/admin/api/auth (`http://BACKEND_URL/admin/api/auth`) and log in.
+This should explicitly generate the missing `api` folder.
+
+#### **Option C (last resort)**
+
+- delete the `.keystone` and `node_modules` folders
+- clean yarn cache `yarn cache clean`
+- restart your computer
+- re-install Keystone `yarn install`
+- start Keystone `yarn dev`
+
+Additionally you can visit http://localhost:3000/admin/api/auth (`http://BACKEND_URL/admin/api/auth`) and log in.
+This should explicitly generate the missing `api` folder.
+
+### Cause
+
+It is unclear at the moment why this error occurs.
+If you come across the root cause of this, please [create a PR](https://github.com/ijsto/keystone-plugins/pulls), or [submit and issue](https://github.com/ijsto/keystone-plugins/issues/new) with your findings, we will add it here so others can benefit from it.

docs/docs/troubleshooting/limitations.md

@@ -0,0 +1,5 @@
+# Limitations
+
+If you run into any limitations, please [submit an issue](https://github.com/ijsto/keystone-plugins/issues/new) and we will add it here.
+
+[Pull Requests](https://github.com/ijsto/keystone-plugins/pulls) are also very welcome. 🙌🏼