From 0afeccfb746f14fb4f0aec5a5de8a862bac9de70 Mon Sep 17 00:00:00 2001
From: 0xEdmundo <0xedmundo@gmail.com>
Date: Thu, 29 Jan 2026 18:02:07 +0300
Subject: [PATCH] docs: add troubleshooting section to README

Add a troubleshooting table with common issues and solutions to help
developers resolve problems quickly without searching multiple resources.

Covers:
- Yarn/Corepack setup issues
- Node version mismatches
- Build memory errors
- Port conflicts
- Dependency resolution
- TypeScript errors

Closes #2887
---
 README.md | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/README.md b/README.md
index efa3d4fc42e..93925518300 100644
--- a/README.md
+++ b/README.md
@@ -57,6 +57,21 @@ There are three projects which can be run individually.
 yarn workspace @app/web dev
 ```
 
+## Troubleshooting
+
+Common issues and their solutions:
+
+| Issue | Solution |
+|-------|----------|
+| `yarn` command not found | Enable Corepack: `corepack enable` |
+| Node version mismatch | Run `nvm use` to load the correct Node.js version |
+| Build fails with memory error | Increase Node memory: `export NODE_OPTIONS="--max_old_space_size=4096"` |
+| Port already in use | Kill the process: `lsof -i :3000` then `kill -9 <PID>`, or use a different port |
+| Dependencies not resolving | Clear cache: `yarn cache clean` and reinstall: `yarn install --force` |
+| TypeScript errors after pull | Run `yarn build` to regenerate type definitions |
+
+For additional help, join the [Base Discord](https://base.org/discord) and ask in #developer-chat.
+
 ## Contributing
 
 We welcome contributions to Base! For guidelines on how to contribute please refer to [CONTRIBUTING.md](CONTRIBUTING.md).