docs(readme): add troubleshooting section with common issues and solutions

Author: josecelano

README.md

@@ -4,7 +4,7 @@
 
 A web service to get torrents' metadata from the infohashes.
 
-The API is based on the Rust BitTorrent client [rqbit](<https://github.com/ikatson/rqbit>). The client uses [BEP 9](https://www.bittorrent.org/beps/bep_0009.html) to get the Metadata Files from other peers.
+The API is based on the Rust BitTorrent client [rqbit](https://github.com/ikatson/rqbit). The client uses [BEP 9](https://www.bittorrent.org/beps/bep_0009.html) to get the Metadata Files from other peers.
 
 > NOTICE: DHT must be enabled because the client needs to find peers first.
 
@@ -43,6 +43,49 @@ Or with the browser:
 
 You can check the API with the health_check endpoint: <http://127.0.0.1:3000/health_check>
 
+## Troubleshooting
+
+### Tokio Runtime Error
+
+If you encounter an error like:
+
+```text
+Registering a blocking socket with the tokio runtime is unsupported. If you wish to do anyways, please add `--cfg tokio_allow_from_blocking_fd` to your RUSTFLAGS.
+```
+
+You need to set the RUSTFLAGS environment variable when building and running the application:
+
+```console
+RUSTFLAGS="--cfg tokio_allow_from_blocking_fd" cargo run
+```
+
+This is a known issue with the tokio runtime on certain systems. The flag allows the application to register blocking file descriptors with the async runtime.
+
+### Session Directory Not Found
+
+If you see an error about the session output directory not being found:
+
+```text
+Error: Session output directory not found: /var/lib/torrust/hash2torrent/session
+```
+
+Make sure you've run the setup script first:
+
+```console
+sudo ./contrib/dev-tools/init/install.sh $(id -u)
+```
+
+This script creates the necessary directories with proper permissions for the BitTorrent client session data.
+
+### Torrent Not Found (408 Timeout)
+
+The BitTorrent client needs to find peers through DHT before it can download the metadata. This process can take time, and the request may timeout (10 seconds default). If this happens:
+
+- DHT needs time to bootstrap and find peers
+- Try the request again after a few moments
+- Some torrents may have very few or no active peers
+- Check that your network allows DHT traffic on the configured port
+
 ## Acknowledgments
 
-[ikatson](<https://github.com/ikatson>) main contributor to [rqbit](https://github.com/ikatson/rqbit).
+[ikatson](https://github.com/ikatson) main contributor to [rqbit](https://github.com/ikatson/rqbit).

cSpell.json

@@ -14,6 +14,7 @@
         "comms",
         "Containerfile",
         "distroless",
+        "dtolnay",
         "ikatson",
         "infohash",
         "letsencrypt",
@@ -25,6 +26,8 @@
         "realpath",
         "reqwest",
         "rqbit",
+        "RUSTDOCFLAGS",
+        "RUSTFLAGS",
         "serde",
         "Slowloris",
         "thiserror",