From 7eddb90e44ff11c51b7ca28e3334ebd286d07231 Mon Sep 17 00:00:00 2001
From: Hermes Agent <root@okwn.cc>
Date: Sun, 24 May 2026 09:23:40 +0000
Subject: [PATCH] docs: add error handling section to README

---
 README.md | 58 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 58 insertions(+)

diff --git a/README.md b/README.md
index 51d5474..3c3aea4 100644
--- a/README.md
+++ b/README.md
@@ -78,6 +78,64 @@ Quick links:
 - [SAP HANA Support](https://awuqing.github.io/BackupX/docs/features/sap-hana) — hdbsql Runner and native Backint
 - [API Reference](https://awuqing.github.io/BackupX/docs/reference/api) — REST endpoints
 
+## Error Handling
+
+BackupX provides structured error handling to help you diagnose and resolve issues quickly.
+
+### Log Locations
+
+| Environment | Log Path |
+|-------------|----------|
+| Docker | `docker logs <container>` |
+| Binary ( systemd ) | `journalctl -u backupx` |
+| Binary ( manual ) | `./backupx logs` or console output |
+
+### Common Issues
+
+**Backup task fails with "connection refused"**
+
+- Verify the storage backend credentials are correct and the endpoint is reachable
+- Check firewall rules allow outbound connections to your storage provider
+- For S3-compatible backends, ensure the region and endpoint URL are correctly configured
+
+**Agent node appears offline**
+
+- Confirm the Agent process is running on the remote node
+- Verify network connectivity between the master and Agent (default port 8340)
+- Check the Agent logs for authentication or certificate errors
+
+**Database backup hangs or times out**
+
+- Increase the `timeout` value in the backup task settings
+- For large databases, enable incremental or differential backup modes
+- Ensure the database user has sufficient privileges (e.g., `LOCK TABLES`, `SELECT` for MySQL)
+
+**Webhook or notification failures**
+
+- Verify the webhook URL is publicly accessible
+- Check that the HMAC secret matches between BackupX and your receiver
+- Ensure the target server accepts POST requests with JSON payload
+
+### Debug Mode
+
+Enable verbose logging for troubleshooting:
+
+```bash
+# Binary
+./backupx --log-level debug
+
+# Docker
+docker run -d --name backupx -p 8340:8340 -e LOG_LEVEL=debug awuqing/backupx:latest
+```
+
+### Getting Help
+
+If you encounter an error not listed here:
+
+1. Check the [troubleshooting guide](https://awuqing.github.io/BackupX/docs/guides/troubleshooting) in the docs
+2. Search [existing issues](https://github.com/Awuqing/BackupX/issues) for similar errors
+3. Open a new issue with the error message, log excerpts, and your configuration
+
 ## Development
 
 ```bash