[DOCS] Add Troubleshooting Guide for Common Setup Errors

[piyush10854]

Description

The current README provides good setup instructions, but it lacks a dedicated troubleshooting section for common development/setup issues.

Many beginners may face problems while:

• running Docker containers
• configuring .env
• connecting Redis
• applying Alembic migrations
• starting frontend/backend servers
• configuring Groq/Supabase keys

Adding a troubleshooting guide will improve contributor onboarding and reduce repeated setup questions.

Proposed Changes

Add a new Troubleshooting section in README covering:

• Redis connection errors
• Port already in use issues
• Docker build failures
• Missing .env variables
• Alembic migration errors
• Frontend API connection issues
• Windows command alternatives were needed

Benefits

• Better beginner onboarding
• Easier local setup
• Reduced contributor confusion
• Improved documentation quality

I would like to work on this issue as part of GSSoC.

[github-actions]

👋 Hey @piyush10854, thanks for raising this issue!

A maintainer will review it shortly. If you'd like to work on a fix, please read the guidelines below before opening a PR.

---

📋 Before You Start

Look at our merged pull requests to understand the expected commit style and code quality before writing a single line.

Merged PRs are the best source of truth for:

• How commits should be worded and structured
• How code is organised (file structure, naming, patterns)
• What a clean, reviewable PR looks like

---

✅ Clean Commit History — Required

We follow Conventional Commits:

Prefix	Use for
feat:	New feature
fix:	Bug fix
chore:	Tooling / config / deps
docs:	Documentation only
refactor:	Code restructuring (no behaviour change)
test:	Adding or fixing tests

Branch naming: feat/<short-description> or fix/<short-description>

Rules:

• 🚫 No force-push to main or shared branches
• 🚫 No merge commits inside your feature branch — rebase instead
• ✅ One logical change per commit
• ✅ PR must reference this issue: Closes #121

---

Happy contributing! 🚀

[piyush10854]

Hi @Team-NoxVeil,
I would like to work on this issue as part of GSSoC.
Please assign it to me.

[shaikummekulsum2712-hub]

This is a critical improvement for contributor onboarding. The current setup documentation, while functional, lacks a dedicated section to address common pitfalls, leading to unnecessary friction for new users.

My plan is to introduce a new Troubleshooting section within the README.md. This section will systematically detail common setup errors related to Docker, Redis, environment configuration, and database migrations, providing clear, actionable steps for resolution. This will significantly reduce repeated inquiries and streamline the initial setup experience. assign this issue to me. if available!

[Saann20]

Hi @piyush10854 I’m a GSSoC’26 contributor and would like to work on this issue. I’d like to create a detailed troubleshooting guide for common setup and development issues to make onboarding easier for new contributors and users.

My contribution will include:

• Common installation and dependency errors
• Docker and environment setup troubleshooting
• Backend/frontend startup issues and fixes
• Port conflict and database connection solutions
• Beginner-friendly explanations with organized documentation
• Platform-specific notes where necessary

Since many contributors may face setup-related difficulties while working with the project, I believe this guide would significantly improve the developer experience and onboarding process. I would be happy to contribute this under GSSoC’26. Could you please assign this issue to me?

[Akshitha2912v]

Hi @Team-NoxVeil, I’d like to work on this issue under GSSoC’26. I can add a troubleshooting guide covering common setup and runtime errors to help contributors resolve issues more easily. Kindly assign this issue to me. Thank you!

[Anushreer22]

Hi @Team-NoxVeil 👋

I’m a GSSoC 2026 contributor and I would like to work on this documentation improvement.

I can create a well-structured Troubleshooting section in the README covering:

• Redis connection issues
• Docker build/runtime errors
• missing .env configuration problems
• Alembic migration failures
• frontend/backend startup issues
• API connection problems
• Windows command alternatives and platform-specific fixes

I’ll make the guide beginner-friendly with clear explanations, organized sections, and practical resolution steps to improve contributor onboarding and reduce repetitive setup questions.

I’ll also follow the repository contribution guidelines and conventional commit structure properly.

Could you please assign this issue to me? Thank you!

[PranavAgarkar07]

Hey! I'd love to work on this. I have experience with full-stack development and this seems like a great issue to start contributing. Could you assign me to this?