From dbabbc3778c3d78cefa5100c45e8f4edaf900126 Mon Sep 17 00:00:00 2001 From: Ata-Ul-Hai Date: Wed, 7 Jan 2026 18:43:33 +0530 Subject: [PATCH 1/3] docs: add troubleshooting guide for setup, docker, and vault --- README.md | 2 + docs/TROUBLESHOOTING.md | 100 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 102 insertions(+) create mode 100644 docs/TROUBLESHOOTING.md diff --git a/README.md b/README.md index 3a745b6..27ff7eb 100644 --- a/README.md +++ b/README.md @@ -165,6 +165,8 @@ The application will automatically retry connections (5 times) and provide a det | **Celery Tasks Stuck** | Tasks remain 'Pending' | Check Redis logs: `docker logs spectragraph-redis`. Ensure the worker is initialized. | | **UI Blank Screen** | `VITE_API_URL` error | Ensure `.env` has the correct API host (usually `http://localhost:5001`). | +For additional setup issues and resolutions, see the full [Troubleshooting Guide](./docs/TROUBLESHOOTING.md). + --- ## 🗺 SWoC 2026 Roadmap diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md new file mode 100644 index 0000000..c7608e8 --- /dev/null +++ b/docs/TROUBLESHOOTING.md @@ -0,0 +1,100 @@ +# 🛠 Troubleshooting Guide + +This document lists common setup and development issues encountered while running SpectraGraph locally, along with their causes and resolutions. +If you encounter an issue not listed here, feel free to open an Issue. + +## Docker Services (Neo4j & Redis) + +### Symptom +- `Connection refused` errors on ports `7474` (Neo4j) or `6379` (Redis) +- API fails to start or background tasks remain pending + +### Cause +- Docker containers are not running +- Containers failed during startup +- Docker daemon is not active + +### Solution +1. Verify Docker is running: + ```bash + docker ps +2. Check container status: + ```bash + docker-compose ps +3. Inspect logs for failing services: + ```bash + docker-compose logs neo4j + docker-compose logs redis +4. Restart the stack: + ```bash + make dev + +## Vault Secret Integration + +### Symptom +- Errors related to `MASTER_VAULT_KEY` +- API crashes during startup or secret access +- Integration tests involving Vault fail + +### Cause +- Vault service is not running or unsealed +- Required Vault environment variables are missing +- Vault keys are not exported in the current shell + +### Solution +1. Ensure the Vault container is running: + ```bash + docker ps +2. Verify required environment variables are set: + ```bash + echo $MASTER_VAULT_KEY_V1 +3. If Vault was restarted, re-export keys and tokens before retrying. +4. Re-run the stack after fixing Vault configuration: + ```bash + make dev + +## Python / Poetry Environment Issues + +### Symptom +- `pyproject.toml` installation failures +- Dependency conflicts across `api`, `core`, or `transforms` +- Poetry commands behave inconsistently + +### Cause +- Poetry cache corruption +- Python version mismatch +- Manual setup instead of standardized Makefile workflow + +### Solution +1. Prefer using the Makefile for setup: + ```bash + make dev +2. Clear Poetry cache if installation fails: + ```bash + poetry cache clear pypi --all +3. Ensure the correct Python version is active: + ```bash + python --version +4. Retry installation after clearing cache. + +## Common Port Conflicts + +### Symptom +- `Address already in use` +- Services fail to bind to ports `3000`, `5001`, or `5432` + +### Cause +- Another local service is already using the required port + +### Solution +1. Identify the process using the port: + ```bash + lsof -i :3000 +2. Stop the conflicting process or free the port: + ```bash + kill -9 +3. Restart the SpectraGraph stack: + ```bash + make dev + + From a391dd5086547b9e3536cfe56eccab3da0857fa3 Mon Sep 17 00:00:00 2001 From: Ata-Ul-Hai Date: Wed, 7 Jan 2026 18:44:18 +0530 Subject: [PATCH 2/3] docs: add troubleshooting guide for setup, docker, and vault --- docs/TROUBLESHOOTING.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md index c7608e8..99c58a5 100644 --- a/docs/TROUBLESHOOTING.md +++ b/docs/TROUBLESHOOTING.md @@ -95,6 +95,4 @@ If you encounter an issue not listed here, feel free to open an Issue. kill -9 3. Restart the SpectraGraph stack: ```bash - make dev - - + make dev \ No newline at end of file From 9ae39ce10b06962f3914ab6bb48f4cff711eff1e Mon Sep 17 00:00:00 2001 From: Ata-Ul-Hai Date: Wed, 7 Jan 2026 19:13:54 +0530 Subject: [PATCH 3/3] docs: fix formatting and improve troubleshooting guide --- docs/TROUBLESHOOTING.md | 71 ++++++++++++++++++++++++----------------- 1 file changed, 42 insertions(+), 29 deletions(-) diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md index 99c58a5..ee9a570 100644 --- a/docs/TROUBLESHOOTING.md +++ b/docs/TROUBLESHOOTING.md @@ -1,7 +1,7 @@ # 🛠 Troubleshooting Guide -This document lists common setup and development issues encountered while running SpectraGraph locally, along with their causes and resolutions. -If you encounter an issue not listed here, feel free to open an Issue. +This document lists common setup and development issues encountered while running SpectraGraph locally, along with their causes and resolutions. +If you encounter an issue not listed here, feel free to open an issue or submit a PR. ## Docker Services (Neo4j & Redis) @@ -16,18 +16,22 @@ If you encounter an issue not listed here, feel free to open an Issue. ### Solution 1. Verify Docker is running: - ```bash - docker ps +```bash +docker ps +``` 2. Check container status: - ```bash - docker-compose ps +```bash +docker-compose ps +``` 3. Inspect logs for failing services: - ```bash - docker-compose logs neo4j - docker-compose logs redis +```bash +docker-compose logs neo4j +docker-compose logs redis +``` 4. Restart the stack: - ```bash - make dev +```bash +make dev +``` ## Vault Secret Integration @@ -43,15 +47,18 @@ If you encounter an issue not listed here, feel free to open an Issue. ### Solution 1. Ensure the Vault container is running: - ```bash - docker ps +```bash +docker ps +``` 2. Verify required environment variables are set: - ```bash - echo $MASTER_VAULT_KEY_V1 +```bash +echo $MASTER_VAULT_KEY_V1 +``` 3. If Vault was restarted, re-export keys and tokens before retrying. 4. Re-run the stack after fixing Vault configuration: - ```bash - make dev +```bash +make dev +``` ## Python / Poetry Environment Issues @@ -67,14 +74,17 @@ If you encounter an issue not listed here, feel free to open an Issue. ### Solution 1. Prefer using the Makefile for setup: - ```bash - make dev +```bash +make dev +``` 2. Clear Poetry cache if installation fails: - ```bash - poetry cache clear pypi --all +```bash +poetry cache clear pypi --all +``` 3. Ensure the correct Python version is active: - ```bash - python --version +```bash +python --version +``` 4. Retry installation after clearing cache. ## Common Port Conflicts @@ -88,11 +98,14 @@ If you encounter an issue not listed here, feel free to open an Issue. ### Solution 1. Identify the process using the port: - ```bash - lsof -i :3000 +```bash +lsof -i :3000 +``` 2. Stop the conflicting process or free the port: - ```bash - kill -9 +```bash +kill -9 +``` 3. Restart the SpectraGraph stack: - ```bash - make dev \ No newline at end of file +```bash +make dev +``` \ No newline at end of file