Troubleshooting Guide¶

Обзор¶

Comprehensive troubleshooting guide для решения типичных проблем при разработке Saga DeFi Platform.

Emergency Quick Fixes¶

System Won't Start¶

# Quick diagnosis
make status

# Force restart
make restart

# Check logs
docker logs saga --tail=100

# Nuclear option (WARNING: destroys data)
make stop
docker system prune -af
make restart

Tests Failing Unexpectedly¶

# Check system is running
make status

# Restart and rerun tests
make restart
make smoke

# Check for stale processes
ps aux | grep saga
ps aux | grep anvil

🐳 Docker Issues¶

Container Won't Start¶

Symptom: make restart fails, docker ps shows no saga container

Diagnosis:

# Check all containers (including stopped)
docker ps -a

# Check Docker logs
docker logs saga

# Check for port conflicts
lsof -i :8080
lsof -i :8081
lsof -i :8082

Solutions:

# Kill processes on ports
kill -9 $(lsof -t -i:8080)

# Remove stopped containers
docker container prune -f

# Rebuild container
make cold-restart

Port Already in Use¶

Error: bind: address already in use

Solution:

# Find process using port
lsof -i :8080

# Kill process
kill -9 <PID>

# Or kill all saga processes
pkill saga
pkill anvil

# Restart
make restart

Docker Daemon Not Running¶

Error: Cannot connect to the Docker daemon

Solution:

# Start Docker service
sudo systemctl start docker

# Enable Docker on boot
sudo systemctl enable docker

# Add user to docker group (logout required)
sudo usermod -aG docker $USER
newgrp docker

Out of Disk Space¶

Symptom: Container fails, "no space left on device"

Solution:

# Check disk usage
df -h

# Clean Docker system
docker system prune -af --volumes

# Remove old images
docker image prune -af

# Clean build cache
docker builder prune -af

🗄️ Database Issues¶

Can't Connect to Database¶

Error: connection refused или could not connect to server

Diagnosis:

# Check PostgreSQL is running
pg_isready -h 127.0.0.1 -p 5432

# Check if port is open
lsof -i :5432

# Check PostgreSQL status
systemctl status postgresql

Solutions:

# Start PostgreSQL
sudo systemctl start postgresql

# Check connection
psql -U aisee -h 127.0.0.1 -d saga

# Check credentials in .env
cat .env | grep DB_PASSWORD

Migration Fails¶

Error: migration failed или duplicate key value

Diagnosis:

# Check current migration version
docker exec saga /app/bin/migrate version

# Check migration logs
docker logs saga | grep migration

Solutions:

# Rollback one migration
docker exec saga /app/bin/migrate down

# Reset database (WARNING: destroys data)
docker exec saga /app/bin/migrate reset
docker exec saga /app/bin/migrate up

# Force specific version
docker exec saga /app/bin/migrate force <version>

Database Locked¶

Error: database is locked или too many connections

Solution:

# Check active connections
psql -U aisee -h 127.0.0.1 -d saga -c "SELECT count(*) FROM pg_stat_activity"

# Kill idle connections
psql -U aisee -h 127.0.0.1 -d saga -c "SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE state = 'idle' AND pid <> pg_backend_pid()"

# Restart PostgreSQL
sudo systemctl restart postgresql

⛓️ Blockchain Issues¶

VPS Blockchain Not Responding¶

Error: connection refused на port 8545

Diagnosis:

# Check VPS blockchain status
make -f makefiles/development.mk vps-status

# Check RPC directly
curl -X POST -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' \
  http://188.42.218.164:8545

Solutions:

# SSH to VPS and check Anvil
ssh cloud-user@188.42.218.164
systemctl status anvil

# Restart Anvil on VPS
ssh cloud-user@188.42.218.164 'systemctl restart anvil'

# Check firewall
ssh cloud-user@188.42.218.164 'ufw status'

Contract Not Deployed¶

Error: Contract not found at address

Solution:

# Re-deploy all contracts
make -f makefiles/development.mk vps-init

# Check contract addresses
cat .env | grep CONTRACT

# Verify deployment
cast call <CONTRACT_ADDRESS> "name()(string)" --rpc-url http://188.42.218.164:8545

Transaction Failing¶

Error: execution reverted, gas estimation failed

Diagnosis:

# Check account balance
cast balance <ADDRESS> --rpc-url http://188.42.218.164:8545

# Check gas price
cast gas-price --rpc-url http://188.42.218.164:8545

# Check nonce
cast nonce <ADDRESS> --rpc-url http://188.42.218.164:8545

Solutions:

# Fund account
make -f makefiles/development.mk vps-fund-address ADDRESS=<ADDRESS>

# Increase gas limit in transaction
# Check contract code for revert reasons

Test Issues¶

E2E Tests Timing Out¶

Error: TimeoutError: waiting for locator

Solutions:

# Increase timeout in playwright.config.ts
timeout: 60000  # 60 seconds

# Run with headed mode to debug
npx playwright test --headed

# Check backend is running
make status
docker logs saga --tail=50

JWT Token Invalid¶

Error: signature is invalid, token expired

Solutions:

# Regenerate admin token
make jwt-admin-token EMAIL=admin@saga-test.com

# Check JWT_SECRET matches
grep JWT_SECRET .env
docker exec saga printenv JWT_SECRET

# Update test config
vim frontend/e2e/shared/config/test-config.ts

Tests Pass Locally But Fail in CI¶

Common Issues:

Timing differences (CI is slower)
Environment variables missing
Database not properly reset between tests
Port conflicts

Solutions:

# Add explicit waits in tests
await page.waitForLoadState('networkidle');

# Check CI environment variables
cat .github/workflows/*.yml

# Add retry logic
test.describe.configure({ retries: 2 });

Build Issues¶

Go Build Fails¶

Error: cannot find package, undefined: X

Solutions:

# Update dependencies
go mod tidy
go mod download

# Clear module cache
go clean -modcache

# Verify imports
go list -m all

# Check Go version
go version  # Should be 1.21+

Frontend Build Fails¶

Error: Module not found, Cannot find module

Solutions:

# Clear npm cache
npm cache clean --force

# Remove node_modules
rm -rf frontend/*/node_modules
rm -rf frontend/*/package-lock.json

# Reinstall dependencies
cd frontend/user-app && npm install
cd frontend/admin-app && npm install

# Check Node version
node --version  # Should be 18+

TypeScript Errors¶

Error: Property 'X' does not exist on type 'Y'

Solutions:

# Regenerate types from Go structs
make generate-types

# Check TypeScript version
cd frontend/user-app && npx tsc --version

# Strict mode issues
vim tsconfig.json
# Temporarily disable: "strict": false

Frontend Issues¶

MetaMask Not Connecting¶

Symptoms: "Connect Wallet" button does nothing

Solutions:

# Check MetaMask installed
# Browser DevTools → Extensions

# Add Saga network manually
# Network Name: Saga Testnet
# RPC URL: http://188.42.218.164:8545
# Chain ID: 1337
# Currency Symbol: ETH

# Clear MetaMask cache
# Settings → Advanced → Reset Account

404 on API Calls¶

Error: 404 Not Found on /api/* endpoints

Diagnosis:

# Check backend is running
make status

# Check API routes
docker logs saga | grep "Registered route"

# Test endpoint directly
curl http://localhost:8080/api/health

Solutions:

# Restart backend
make restart

# Check CORS settings
cat config.yaml | grep cors

# Verify URL in frontend
vim frontend/shared/config/api-config.ts

Console Errors on 401 Responses¶

Issue: Red errors for normal auth checks

Solution: This is a known architectural issue. 401 responses from auth endpoints are normal for unauthenticated users. See /docs/guides/frontend-debugging.md for handling approach.

Performance Issues¶

Slow Test Execution¶

Symptoms: Tests take 10+ minutes

Solutions:

# Run specific test groups
make e2e-smoke  # Only critical tests

# Parallel execution
make test-all  # Uses parallel architecture

# Check system resources
htop
docker stats

# Increase test timeout
vim frontend/e2e/playwright.config.ts

High Memory Usage¶

Symptoms: System sluggish, OOM errors

Diagnosis:

# Check memory usage
free -h
docker stats

# Check for memory leaks
docker logs saga | grep -i "memory\|oom"

Solutions:

# Increase Docker memory limit
# Docker Desktop → Resources → Memory → 8GB+

# Clear Docker cache
docker system prune -af

# Restart system
sudo reboot

Network Issues¶

Can't Reach VPS¶

Error: connection timeout to 188.42.218.164

Diagnosis:

# Check VPS is up
ping 188.42.218.164

# Check SSH access
ssh cloud-user@188.42.218.164 'uptime'

# Check specific ports
nc -zv 188.42.218.164 8545  # Blockchain
nc -zv 188.42.218.164 8080  # Nginx

Solutions:

# Check VPS firewall
ssh cloud-user@188.42.218.164 'ufw status'

# Restart services on VPS
ssh cloud-user@188.42.218.164 'systemctl restart nginx anvil'

# Contact VPS provider if down

Authentication Issues¶

JWT Token Expired¶

Error: token is expired, unauthorized

Solution:

# Generate new token
make jwt-admin-token EMAIL=admin@saga-test.com

# Update token in tests
vim frontend/e2e/shared/config/test-config.ts

Admin Access Denied¶

Error: insufficient permissions

Solution:

# Check admin email is in config
cat config.yaml | grep admin_emails

# Regenerate admin token with correct email
make jwt-admin EMAIL=admin@saga-test.com

Documentation Issues¶

Broken Links in Docs¶

Solution:

# Run documentation analyzer
./bin/documentation-analyzer

# Check specific link
# Navigate to file and verify target exists

# Report issue
# Create GitHub issue with link details

🆘 Getting Help¶

Before Asking for Help¶

✅ Read error message carefully
✅ Check this troubleshooting guide
✅ Run make status to verify system state
✅ Check logs: docker logs saga --tail=100
✅ Try make restart
✅ Search GitHub issues

Where to Ask¶

GitHub Issues: Bug reports, feature requests
Telegram: @AiSeeQ для быстрых вопросов
Documentation: Check /docs for guides

Information to Include¶

# System info
uname -a
go version
node --version
docker --version

# Error logs
docker logs saga --tail=100

# System status
make status
docker ps -a

📋 Метаданные¶

Версия: 2.4.82

Обновлено: 2025-10-21

Статус: Published

Troubleshooting Guide¶

Обзор¶

Emergency Quick Fixes¶

System Won't Start¶

Tests Failing Unexpectedly¶

🐳 Docker Issues¶

Container Won't Start¶

Port Already in Use¶

Docker Daemon Not Running¶

Out of Disk Space¶

🗄️ Database Issues¶

Can't Connect to Database¶

Migration Fails¶

Database Locked¶

⛓️ Blockchain Issues¶

VPS Blockchain Not Responding¶

Contract Not Deployed¶

Transaction Failing¶

Test Issues¶

E2E Tests Timing Out¶

JWT Token Invalid¶

Tests Pass Locally But Fail in CI¶

Build Issues¶

Go Build Fails¶

Frontend Build Fails¶

TypeScript Errors¶

Frontend Issues¶

MetaMask Not Connecting¶

404 on API Calls¶

Console Errors on 401 Responses¶

Performance Issues¶

Slow Test Execution¶

High Memory Usage¶

Network Issues¶

Can't Reach VPS¶

Authentication Issues¶

JWT Token Expired¶

Admin Access Denied¶

Documentation Issues¶

Broken Links in Docs¶

🆘 Getting Help¶

Before Asking for Help¶

Where to Ask¶

Information to Include¶

Related Documentation¶

📋 Метаданные¶