Troubleshooting Guide¶
Common issues and solutions for Certana development and deployment.
Backend Issues¶
Database Connection Error¶
sqlalchemy.exc.OperationalError: could not connect to server
Solution:
# Check PostgreSQL is running
pg_isready -h localhost -p 5432
# Start PostgreSQL
brew services start postgresql # macOS
sudo systemctl start postgresql # Linux
# Check connection string in .env
DATABASE_URL=postgresql+asyncpg://certana:certana@localhost:5432/certana
Import Error: No module named 'torch'¶
ModuleNotFoundError: No module named 'torch'
Solution:
# Install PyTorch
pip install torch torchvision
# Or CPU-only version
pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu
CUDA Out of Memory¶
RuntimeError: CUDA out of memory
Solution:
# Use CPU instead
export CUDA_VISIBLE_DEVICES=
# Or use specific GPU
export CUDA_VISIBLE_DEVICES=0
# Or enable mixed precision
TORCH_DTYPE=float16
Port Already in Use (8000)¶
Address already in use
Solution:
# Find process
lsof -i :8000
# Kill process
kill -9 <PID>
# Or use different port
python -m uvicorn src.main:app --port 8001
Migration Errors¶
alembic.util.exc.CommandError: Can't find identifier in the script
Solution:
# Check current version
alembic current
# View history
alembic history
# Downgrade one step
alembic downgrade -1
# Upgrade to specific revision
alembic upgrade <revision>
Rate Limiting Not Working¶
Solution:
# Ensure Redis is running
redis-cli ping
# Check RATE_LIMIT_ENABLED in .env
RATE_LIMIT_ENABLED=true
# Restart backend
Frontend Issues¶
Port Already in Use (3000)¶
Something is already running on port 3000
Solution:
# Kill process
lsof -i :3000
kill -9 <PID>
# Or use different port
PORT=3001 npm start
Dependency Installation Fails¶
npm ERR! code E404
npm ERR! 404 Not Found
Solution:
# Clear npm cache
npm cache clean --force
# Delete node_modules and package-lock.json
rm -rf node_modules package-lock.json
# Reinstall
npm install
Module Not Found¶
Cannot find module '@react-navigation/...'
Solution:
# Install missing peer dependencies
npm install @react-navigation/native @react-navigation/bottom-tabs
# Or install all at once
npm install
Hot Reload Not Working¶
Solution:
# Restart development server
npm start
# Clear Metro bundler cache
npm start -- --reset-cache
# Or manually
rm -rf node_modules/.cache
Extension Issues¶
Extension Not Appearing¶
Solution:
# Rebuild
npm run build
# Reload in browser
# Chrome: chrome://extensions/ → reload icon
# Firefox: about:debugging → reload
# Check for errors in console
CORS Errors¶
Access to XMLHttpRequest blocked by CORS policy
Solution:
Backend (add to CORS origins):
CORS_ORIGINS=["moz-extension://...", "chrome-extension://..."]
Or use host_permissions in manifest:
"host_permissions": ["<all_urls>"]
Storage Permission Error¶
chrome.storage is undefined
Solution:
Add to manifest.json:
"permissions": ["storage", "contextMenus"]
API Key Validation Fails¶
Solution:
# Check API key is valid
curl -X POST http://localhost:8000/v1/api-keys/validate \
-H "X-API-Key: your-key"
# Verify API endpoint is correct
# Check VITE_API_URL in .env
# Check backend CORS includes extension origin
Deployment Issues¶
Database Migration Failed¶
ERROR: relation "users" already exists
Solution:
# Check existing tables
psql -d certana -c "\dt"
# Drop existing schema (dev only!)
psql -d certana -c "DROP SCHEMA public CASCADE; CREATE SCHEMA public;"
# Re-run migrations
alembic upgrade head
Health Check Failing¶
Service unavailable / health check failed
Solution:
# Check endpoint
curl http://localhost:8000/health
# Check backend logs
docker logs <container-id>
# Verify database connection
psql -U certana -d certana -c "SELECT 1;"
# Restart service
docker-compose restart backend
Image Upload Fails¶
413 Request Entity Too Large
Solution:
Increase upload size limit in configuration:
# src/main.py
app = FastAPI(...) # Adjust timeout
Or in reverse proxy (nginx):
client_max_body_size 100M;
Blockchain Transaction Timeout¶
Timeout waiting for transaction confirmation
Solution:
# Check Solana RPC endpoint is reachable
curl https://api.devnet.solana.com -X POST \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"getHealth"}'
# Check network status
# https://status.solana.com/
# Increase timeout in config
BLOCKCHAIN_CONFIRMATION_TIMEOUT=60
Common Error Messages¶
| Error | Cause | Solution |
|---|---|---|
EADDRINUSE |
Port in use | Kill process or use different port |
ENOENT |
File not found | Check file path, file exists |
EACCES |
Permission denied | Check file permissions, use sudo if needed |
ENOMEM |
Out of memory | Increase system RAM, close other apps |
ETIMEDOUT |
Connection timeout | Check network, increase timeout value |
ECONNREFUSED |
Connection refused | Check service is running, correct host/port |
Performance Issues¶
Backend Slow Response¶
# Check database query performance
EXPLAIN ANALYZE SELECT * FROM assets WHERE content_hash = '...';
# Monitor resource usage
top # CPU & memory
iostat # Disk I/O
netstat # Network
# Check logs for slow queries
grep "slow" backend.log
Frontend Slow Navigation¶
# Profile with React DevTools
# Chrome → DevTools → Profiler tab
# Check for unnecessary re-renders
React.memo(Component)
# Lazy load screens
const Screen = lazy(() => import('./Screen'))
Extension Slow Verification¶
# Check API response time
curl -w "@curl-format.txt" -o /dev/null -s \
-X POST http://localhost:8000/v1/verify/
# Optimize image before upload
// Compress image in content script
Getting Help¶
Debug Logs¶
Enable debug logging:
# Backend
export LOG_LEVEL=DEBUG
# Frontend
export REACT_APP_LOG_LEVEL=debug
# Extension
export VITE_ENV=development
Check Logs¶
# Backend logs
docker logs certana_backend
# PostgreSQL logs
tail -f /var/log/postgresql/postgresql.log
# Browser console logs
Open DevTools → Console tab
# Browser extension logs
chrome://extensions/ → Details → Errors
about:debugging → Extension → Errors
Useful Commands¶
# Database inspection
psql -d certana -c "\dt" # List tables
psql -d certana -c "\d assets" # Table schema
psql -d certana -c "SELECT COUNT(*) FROM assets;"
# API testing
curl -X GET http://localhost:8000/v1/assets/
curl -X POST -F "file=@image.png" http://localhost:8000/v1/verify/
# Network inspection
tcpdump -i eth0 -n "tcp port 5432"
# Process monitoring
ps aux | grep python
ps aux | grep node
Still Need Help?¶
- Check Backend Documentation
- Check Frontend Documentation
- Check Extension Documentation
- Open an issue on GitHub
- Contact the team
Note: Always check logs first! Most issues can be diagnosed from error messages.