docs: Add troubleshooting guide for HyperSync installation

README.md

@@ -33,3 +33,44 @@ Next, add your HyperSync token to the `.env` file. You can then run an example u
 ```bash
 python examples/<example>.py
 ```
+
+## Troubleshooting
+
+### HyperSync Installation Issues
+
+If you encounter build errors when installing `hypersync`, ensure Rust and system dependencies are installed.
+
+**Ubuntu/Debian:**
+```bash
+# Install all required dependencies
+sudo apt-get update
+sudo apt-get install build-essential capnproto libcapnp-dev
+
+# Install Rust (if not already installed)
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+source $HOME/.cargo/env
+```
+
+**macOS:**
+```bash
+# Install Xcode command line tools
+xcode-select --install
+
+# Install Cap'n Proto via Homebrew
+brew install capnp
+
+# Install Rust (if not already installed)
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+source $HOME/.cargo/env
+```
+
+**Then install hypersync:**
+```bash
+pip install --no-cache-dir --use-pep517 "hypersync==0.8.5"
+```
+
+Common errors:
+- **"cargo not found"**: Install Rust toolchain
+- **"capnp: No such file or directory"**: Install Cap'n Proto (`apt-get install capnproto libcapnp-dev` on Ubuntu, `brew install capnp` on macOS)
+- **Build fails on Linux**: Install build essentials: `apt-get install build-essential`
+