Skip to content

docs: add troubleshooting section to README #643

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
ankitasahu83964 wants to merge 1 commit into from
Closed

docs: add troubleshooting section to README #643

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
61 changes: 61 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -257,6 +257,67 @@ That's it. Zero config for default settings, or customize via the [.env.example]

---

## 🛠️ Troubleshooting

If you encounter issues while setting up AgentWatch, try these common fixes.

### ModuleNotFoundError

If you see a `ModuleNotFoundError`, one or more required Python packages may be missing.

```bash
pip install -r requirements.txt
```

If you're using a virtual environment, make sure it is activated before installing dependencies.

### Docker not running

Some AgentWatch features require Docker.

```bash
docker --version
docker ps
```

If Docker isn't running, start Docker Desktop (Windows/macOS) or the Docker service (Linux).

### Port already in use

```md
### Port already in use

If the application cannot start because a port is occupied, check the default AgentWatch ports and stop the process using that port.

Default ports:

- API: `8000`
- Frontend Dashboard: `3000`

Linux/macOS:

```bash
lsof -i :8000
lsof -i :3000

### Python version mismatch

Verify your Python version:

```bash
python --version
```

Use the version recommended in this README.

### Missing environment variables

Create your environment file:

```bash
cp .env.example .env
Then update the required configuration values before running the application.
Comment on lines +313 to +319

@coderabbitai coderabbitai Bot Jul 21, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Add a Windows command for creating .env.

cp is unavailable in standard Windows PowerShell/cmd, so this remediation can fail for Windows users. Add Copy-Item .env.example .env for PowerShell or copy .env.example .env for cmd.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@README.md` around lines 311 - 319, Add Windows-compatible environment file
creation commands to the “Missing environment variables” section alongside the
existing Unix cp command: include Copy-Item for PowerShell and copy for cmd,
while preserving the instruction to update required configuration values.

Comment thread
ankitasahu83964 marked this conversation as resolved.

## 🔌 Supported Frameworks

AgentWatch wraps your existing agent. **You change nothing.** Detailed guides for each framework live in the [`docs/adapters/`](docs/adapters/) directory.
Expand Down
Loading