# 🔧 NoctisAI Troubleshooting Guide
This guide helps you diagnose and fix common issues with NoctisAI installation and operation.
## 🚀 Quick Health Check
Before diving into specific issues, run the health check:
```bash
cd /home/yenn/NoctisAI
python scripts/health_check.py
```
Or run the comprehensive test suite:
```bash
python scripts/test_noctisai.py
```
## 📋 Common Issues & Solutions
### 1. **Python Environment Issues**
#### ❌ **Issue: "Python version too old"**
```
Error: Python 3.8+ required, found 3.7.x
```
**Solution:**
```bash
# Check current Python version
python3 --version
# Install Python 3.8+ (Ubuntu/Debian)
sudo apt update
sudo apt install python3.8 python3.8-venv python3.8-pip
# Or use pyenv for version management
curl https://pyenv.run | bash
pyenv install 3.11.0
pyenv global 3.11.0
```
#### ❌ **Issue: "No virtual environment detected"**
```
WARNING: No virtual environment detected
```
**Solution:**
```bash
# Create and activate virtual environment
cd /home/yenn/NoctisAI
python3 -m venv noctis-env
source noctis-env/bin/activate
# Verify activation
which python
# Should show: /home/yenn/NoctisAI/noctis-env/bin/python
```
### 2. **Dependency Issues**
#### ❌ **Issue: "Missing dependencies"**
```
Error: No module named 'fastapi'
Error: No module named 'mcp'
```
**Solution:**
```bash
# Activate virtual environment
source noctis-env/bin/activate
# Install dependencies
pip install --upgrade pip
pip install -r requirements.txt
# If specific module fails, install individually
pip install fastapi uvicorn mcp requests cryptography
```
#### ❌ **Issue: "Permission denied" during pip install**
```
ERROR: Could not install packages due to an EnvironmentError: [Errno 13] Permission denied
```
**Solution:**
```bash
# Don't use sudo with virtual environments
# Make sure you're in the virtual environment
source noctis-env/bin/activate
# Use --user flag if needed
pip install --user -r requirements.txt
# Or reinstall pip
python -m pip install --upgrade --force-reinstall pip
```
### 3. **File Structure Issues**
#### ❌ **Issue: "File missing" or "Directory not found"**
```
FAILED: File missing: src/noctis_ai/mcp/noctis_mcp.py
```
**Solution:**
```bash
# Check if you're in the right directory
pwd
# Should show: /home/yenn/NoctisAI
# Verify file structure
ls -la src/noctis_ai/mcp/
ls -la scripts/
# If files are missing, re-clone the repository
cd /home/yenn
git clone https://github.com/Yenn503/noctis-ai-mcp.git
cd noctis-ai-mcp
```
#### ❌ **Issue: "Directory not writable"**
```
FAILED: Directory not writable: output
```
**Solution:**
```bash
# Fix permissions
chmod -R 755 /home/yenn/NoctisAI
chmod -R 777 /home/yenn/NoctisAI/output
chmod -R 777 /home/yenn/NoctisAI/logs
# Or create directories with proper permissions
mkdir -p output/thesilencer output/forensics logs
chmod 777 output logs
```
### 4. **MCP Configuration Issues**
#### ❌ **Issue: "MCP configuration not found"**
```
WARNING: MCP configuration not found
```
**Solution:**
```bash
# Create MCP configuration directory
mkdir -p ~/.cursor
# Create mcp.json file
cat > ~/.cursor/mcp.json << 'EOF'
{
"mcpServers": {
"noctis-ai": {
"command": "python",
"args": ["/home/yenn/NoctisAI/run_noctis_mcp.py"],
"env": {
"PYTHONPATH": "/home/yenn/NoctisAI/src"
}
}
}
}
EOF
# Verify configuration
cat ~/.cursor/mcp.json
```
#### ❌ **Issue: "NoctisAI not configured in MCP"**
```
FAILED: MCP configuration - NoctisAI not configured in MCP
```
**Solution:**
```bash
# Edit the MCP configuration
nano ~/.cursor/mcp.json
# Ensure noctis-ai is in mcpServers section
# Restart Cursor after making changes
```
### 5. **Import and Module Issues**
#### ❌ **Issue: "ModuleNotFoundError"**
```
ModuleNotFoundError: No module named 'noctis_ai'
```
**Solution:**
```bash
# Add src to Python path
export PYTHONPATH="/home/yenn/NoctisAI/src:$PYTHONPATH"
# Or run with PYTHONPATH
PYTHONPATH=/home/yenn/NoctisAI/src python run_noctis_mcp.py
# Or install in development mode
cd /home/yenn/NoctisAI
pip install -e .
```
#### ❌ **Issue: "ImportError" in specific modules**
```
ImportError: cannot import name 'generate_payload' from 'noctis_ai.mcp.malware_tools'
```
**Solution:**
```bash
# Check if the function exists in the file
grep -n "def generate_payload" src/noctis_ai/mcp/malware_tools.py
# Reinstall the module
pip uninstall noctis-ai
pip install -e .
# Or check for syntax errors
python -m py_compile src/noctis_ai/mcp/malware_tools.py
```
### 6. **Server and Port Issues**
#### ❌ **Issue: "Port already in use"**
```
Error: [Errno 98] Address already in use
```
**Solution:**
```bash
# Find process using the port
sudo netstat -tulpn | grep :8081
sudo lsof -i :8081
# Kill the process
sudo kill -9 <PID>
# Or change the port in run_noctis_mcp.py
nano run_noctis_mcp.py
# Change port=8081 to port=8082
```
#### ❌ **Issue: "Connection refused"**
```
ConnectionRefusedError: [Errno 111] Connection refused
```
**Solution:**
```bash
# Check if server is running
ps aux | grep noctis
# Start the server
cd /home/yenn/NoctisAI
source noctis-env/bin/activate
python run_noctis_mcp.py
# Check server logs
tail -f logs/noctis_mcp.log
```
### 7. **TheSilencer Integration Issues**
#### ❌ **Issue: "TheSilencer integration error"**
```
Error: TheSilencer integration failed
```
**Solution:**
```bash
# Check if TheSilencer files exist
ls -la src/noctis_ai/mcp/thesilencer_integration.py
# Test TheSilencer directly
python -c "from noctis_ai.mcp.thesilencer_integration import TheSilencerIntegration; print('OK')"
# Check for C compiler
gcc --version
# If not installed: sudo apt install gcc
```
#### ❌ **Issue: "C compilation failed"**
```
Error: gcc: command not found
```
**Solution:**
```bash
# Install C compiler and build tools
sudo apt update
sudo apt install gcc g++ make build-essential
# For Windows development
sudo apt install mingw-w64
# Verify installation
gcc --version
g++ --version
```
### 8. **Network and Connectivity Issues**
#### ❌ **Issue: "Network connectivity error"**
```
requests.exceptions.ConnectionError: HTTPSConnectionPool
```
**Solution:**
```bash
# Test basic connectivity
ping google.com
curl -I https://www.google.com
# Check proxy settings
echo $HTTP_PROXY
echo $HTTPS_PROXY
# If behind corporate firewall, configure proxy
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080
```
#### ❌ **Issue: "SSL certificate verification failed"**
```
SSL: CERTIFICATE_VERIFY_FAILED
```
**Solution:**
```bash
# Update certificates
sudo apt update
sudo apt install ca-certificates
# Or disable SSL verification (not recommended for production)
export PYTHONHTTPSVERIFY=0
```
### 9. **Permission and Security Issues**
#### ❌ **Issue: "Permission denied"**
```
PermissionError: [Errno 13] Permission denied
```
**Solution:**
```bash
# Check file permissions
ls -la /home/yenn/NoctisAI/
# Fix ownership
sudo chown -R $USER:$USER /home/yenn/NoctisAI/
# Fix permissions
chmod -R 755 /home/yenn/NoctisAI/
chmod +x scripts/*.py
```
#### ❌ **Issue: "SELinux blocking execution"**
```
SELinux is preventing execution
```
**Solution:**
```bash
# Check SELinux status
sestatus
# Temporarily disable SELinux (reboot required)
sudo setenforce 0
# Or configure SELinux for Python
sudo setsebool -P allow_execstack 1
```
### 10. **Memory and Resource Issues**
#### ❌ **Issue: "Out of memory"**
```
MemoryError: Unable to allocate array
```
**Solution:**
```bash
# Check available memory
free -h
# Check swap
swapon --show
# Add swap if needed
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
# Monitor memory usage
htop
```
#### ❌ **Issue: "Disk space low"**
```
OSError: [Errno 28] No space left on device
```
**Solution:**
```bash
# Check disk usage
df -h
# Clean up space
sudo apt autoremove
sudo apt autoclean
sudo du -sh /home/yenn/NoctisAI/logs/*
rm -rf /home/yenn/NoctisAI/logs/*.log
# Find large files
find /home/yenn -type f -size +100M -exec ls -lh {} \;
```
## 🔍 Debugging Commands
### **Check System Information**
```bash
# System info
uname -a
lsb_release -a
# Python info
python3 --version
pip --version
which python3
# Environment info
echo $PATH
echo $PYTHONPATH
env | grep -i python
```
### **Check NoctisAI Status**
```bash
# Check if running
ps aux | grep noctis
netstat -tulpn | grep 8081
# Check logs
tail -f /home/yenn/NoctisAI/logs/noctis_mcp.log
# Check configuration
cat ~/.cursor/mcp.json
```
### **Test Individual Components**
```bash
# Test Python imports
python3 -c "import fastapi, uvicorn, mcp; print('Imports OK')"
# Test NoctisAI modules
cd /home/yenn/NoctisAI
python3 -c "from noctis_ai.mcp import noctis_mcp; print('NoctisAI OK')"
# Test TheSilencer
python3 -c "from noctis_ai.mcp.thesilencer_integration import TheSilencerIntegration; print('TheSilencer OK')"
```
## 🆘 Getting Help
### **Before Asking for Help**
1. Run the health check: `python scripts/health_check.py`
2. Run the test suite: `python scripts/test_noctisai.py`
3. Check the logs: `tail -f logs/noctis_mcp.log`
4. Verify your environment setup
### **When Reporting Issues**
Include the following information:
- Operating system and version
- Python version
- Error messages (full traceback)
- Output of health check
- Steps to reproduce the issue
### **Useful Logs**
```bash
# NoctisAI server logs
tail -f logs/noctis_mcp.log
# System logs
journalctl -u your-service-name
# Python error logs
python3 -u run_noctis_mcp.py 2>&1 | tee debug.log
```
## 🎯 Quick Fixes
### **Complete Reset**
```bash
# Stop all processes
pkill -f noctis
# Remove virtual environment
rm -rf noctis-env
# Recreate everything
cd /home/yenn/NoctisAI
python3 -m venv noctis-env
source noctis-env/bin/activate
pip install --upgrade pip
pip install -r requirements.txt
python run_noctis_mcp.py
```
### **Update NoctisAI**
```bash
cd /home/yenn/NoctisAI
git pull origin main
source noctis-env/bin/activate
pip install -r requirements.txt
python scripts/test_noctisai.py
```
### **Clean Installation**
```bash
# Remove old installation
rm -rf /home/yenn/NoctisAI
# Fresh clone
cd /home/yenn
git clone https://github.com/Yenn503/noctis-ai-mcp.git
cd noctis-ai-mcp
# Setup
python3 -m venv noctis-env
source noctis-env/bin/activate
pip install -r requirements.txt
python scripts/test_noctisai.py
```
---
**Remember:** Most issues can be resolved by ensuring you have the correct Python version, virtual environment, and dependencies installed. Always run the health check first! 🏥✨
