Troubleshooting

# Troubleshooting

If you encounter unknown exceptions and errors while using MrDoc, but cannot find the cause, you can troubleshoot the issue using the methods below to avoid ineffective communication and save everyone's time.

## 1. First Determine the Problem Type (Most Critical Step)

First confirm which type of problem you are encountering 👇

| Problem Type    | Common Symptoms           | Priority Troubleshooting             |
| ------- | -------------- | ---------------- |
| ❗ Page Error  | 500 / 404 / Blank screen | ✅ Enable Debug + Check logs |
| ⚠️ Feature Abnormality | Button unresponsive / Operation failed   | ✅ Browser console         |
| 🌐 Request Failure | Loading failure / API error    | ✅ Network requests           |
| ❓ Error Not Understood | Cannot understand English errors        | ✅ Translate + Search        |

👉 **Classify first, then act, otherwise you are troubleshooting blindly.**

## 2. Quick Self-Check (Many Problems End Here)

If you see an **English error**:

It is recommended to directly copy the error message and use:

* Translation tools (Baidu / Youdao)
* Search engines (Google / Bing / Baidu)
* AI (ChatGPT / DeepSeek / Doubao)

and other tools to search and inquire

💡 For example:

```
IntegrityError UNIQUE constraint failed
```

👉 A quick search will basically tell you it is a "database unique constraint conflict"

## 3. Standard Troubleshooting Process (Follow in Order)

### 1. Enable Debug Mode

When the following occurs:

* 500 error
* Page crash
* Backend exception

Enable `debug` mode in the configuration file, which will output detailed error information.

For configuration file details, see: https://doc.mrdoc.pro/doc/3990/#h2-开启站点调试

### 2. Browser Debug Console

#### Console Error Output

On the page where the exception occurs, right-click and select "Inspect" (or directly press F12 on the keyboard) to open the browser's debug console.

You can check whether there is any error information output in the "Console" tab:

![](http://file.mrdoc.pro/mrdoc-oss/img/2023/04/20/2023-04-20_104458_2624190.9230515041405257.png)

#### Network Request Exceptions

You can also find exception-related requests in the "Network" tab and check their request status and response content.

![](http://file.mrdoc.pro/mrdoc-oss/img/2023/04/20/2023-04-20_104643_6248900.054060900972025094.png)

## 4. Check Logs

If you are the deployer, this is **the most critical step**.

📖 Log documentation: [https://doc.mrdoc.pro/doc/45444/](https://doc.mrdoc.pro/doc/45444/)

👉 Logs can tell you:

* Which line of code the error occurred at
* Which API has a problem
* Whether the data is abnormal

## 5. Troubleshooting Priority Summary (Remember This Order)

```
Can search → Search first
Can check frontend → Check console
Involves API → Check Network
Involves backend → Enable Debug + Check logs
```

## 6. Fault Feedback Template

👉 **A question without error information = basically impossible to troubleshoot**

👉 **Screenshots + Logs = The key to solving problems**

If you need to report a fault to seek help, in order to avoid wasting everyone's energy and save everyone's time, please be sure to provide complete and detailed information, including but not limited to:
```
【Basic Information】

1. Deployment method (Docker / Source code / BT Panel, etc.)
2. MrDoc version
3. Database type (SQLite / MySQL / PostgreSQL)

【Problem Description】

4. Page path where the problem occurs
5. Operation steps (how it was triggered)
6. Whether it can be stably reproduced (Always / Intermittent)

【Scope of Impact】

7. Single user or all users
8. Single document or all documents

【Environment Information】

9. Operating system
10. Browser and version

【Key Evidence (Very Important)】

11. Error screenshot (Required)
12. Browser console screenshot
13. Network request screenshot (If available)
14. Backend logs (If available)

【Supplementary Information】

15. Project configuration (If relevant)
16. Document content (If relevant)
17. User permission configuration (If relevant)
18. Storage configuration (If relevant)
```