Skip to content

11 Solucion de Problemas

glitchboi edited this page Oct 30, 2026 · 3 revisions

Problemas Comunes

make install, make run, make serve, make start, make stop, make restart, make verify, make clean, make help. Ejecuta make help para la lista completa.

Port Already in Use

Error: Address already in use: 5000 or 8080

Solution 1 - Kill process:

# Find process
lsof -i :5000
lsof -i :8080

# Kill it
kill <PID>

Solution 2 - Detener Blackwire:

make stop

Solution 3 - Change port:

# Edit backend/main.py
uvicorn.run(app, host="127.0.0.1", port=5001)

Python Version Too Old

Error: Python 3.8+ required

Solution - Instalar versión más reciente Python:

Ubuntu/Debian:

sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update
sudo apt install python3.10 python3.10-venv

Alternativa - Use pyenv:

curl https://pyenv.run | bash
pyenv install 3.10.0
pyenv local 3.10.0

SSL Certificate Not Working

Problem: HTTPS traffic not decrypting

Solution 1 - Reinstall certificate:

rm -rf ~/.mitmproxy
make install

Solution 2 - Verify certificate is installed:

Firefox:

  • Preferences → Certificates → View Certificates → Authorities
  • Search for "mitmproxy"

Chrome:

certutil -d sql:$HOME/.pki/nssdb -L | grep mitmproxy

Solution 3 - Check browser proxy config:

  • Must be localhost:8080
  • Must check "Use for HTTPS"

La app de escritorio no conecta

Problem: La app nativa no muestra datos or "No se puede conectar"

La app de escritorio (PySide6/Qt) corre en el host y habla con el backend por REST (http://127.0.0.1:5000) + WebSocket (ws://127.0.0.1:5000/ws). Si la UI aparece vacía o sin conexión, casi siempre es el backend el que no está arriba.

Check 1 - ¿El backend está corriendo?

curl http://localhost:5000/api/projects
# o arráncalo:
make start

Check 2 - Lanzar la app directamente:

python desktop/run.py

Check 3 - Smoke test sin UI (headless):

python desktop/run.py --selftest

Check 4 - Verificar PySide6 en el venv:

# PySide6 debe estar instalado en el entorno virtual
python -c "import PySide6; print(PySide6.__version__)"

Si el proxy o la app parecen colgados, reinicia el backend:

make restart

Proxy Not Capturing Traffic

Check 1 - Proxy is running:

  • Revisa el widget de control del proxy en la barra de estado (verde = running)

Check 2 - Browser proxy config:

# Should be:
HTTP Proxy: localhost:8080
HTTPS Proxy: localhost:8080

Check 3 - Certificado instalado:

  • See "SSL Certificate Not Working" section

Check 4 - Scope rules:

  • Tab "Scope" → Check include/exclude rules
  • Temporarily remove all rules to test

Extension Not Loading

Problem: La extensión no se carga en la app de escritorio

Check 1 - Archivo existe:

ls backend/extensions/my_extension.py

Check 2 - EXTENSION_META correct:

# Debe tener at minimum:
EXTENSION_META = {
    "name": "my_extension",
    "title": "My Extension",
    "description": "...",
    "default_config": {"enabled": False}
}

Check 3 - register() function:

def register():
    return MyExtensionClass()

Check 4 - Reiniciar y revisar logs:

La descubierta de extensiones ocurre al arrancar, no en runtime. Reinicia tras cualquier cambio en extensiones y busca errores en la salida:

make restart

Database Corruption

Symptoms:

  • "Base de datos bloqueada" errors
  • Requests faltantes
  • Caídas del sistema

Solution 1 - Cerrar todas las conexiones:

make stop
# Espera 5 seconds
make start

Solution 2 - Verificar integridad de la base de datos:

sqlite3 projects/my-project/blackwire.db "PRAGMA integrity_check;"

Solution 3 - Respaldar y recuperar:

# Backup
cp projects/my-project/blackwire.db projects/my-project/blackwire.db.backup

# Recover
sqlite3 projects/my-project/blackwire.db.backup ".dump" | sqlite3 projects/my-project/blackwire.db.new
mv projects/my-project/blackwire.db.new projects/my-project/blackwire.db

venv Not Found

Error: venv/bin/activate: No such file or directory

Solución:

make install

Esto crea el venv, instala requirements.txt y genera el certificado de mitmproxy.


Lanzador de Escritorio Not Working

Problem: Launcher in menu doesn't start BlackWire

El lanzador .desktop se distribuye en assets/blackwire.desktop y ejecuta make -C <ruta> run. make run arranca el backend y lanza la app nativa de escritorio (no abre un navegador). Al instalarlo, los marcadores INSTALL_PATH deben apuntar a la ruta real de tu copia de Blackwire.

Check 1 - Launcher instalado:

ls ~/.local/share/applications/blackwire.desktop

Check 2 - Path correcto:

cat ~/.local/share/applications/blackwire.desktop | grep -E "Exec|Path"

Exec debe ser make -C /ruta/real/a/Blackwire run (sin INSTALL_PATH sin reemplazar).

Solución - Reinstalar el lanzador:

cp assets/blackwire.desktop ~/.local/share/applications/blackwire.desktop
# Reemplaza INSTALL_PATH por la ruta absoluta de tu copia de Blackwire:
sed -i "s|INSTALL_PATH|$(pwd)|g" ~/.local/share/applications/blackwire.desktop

High Memory Usage

Nota: El export de proyectos ahora es streaming (serializa el JSON fila por fila), así que ya no consume RAM proporcional al tamaño del historial. Si veías picos de memoria al exportar, ya no aplican.

Cause: Gran cantidad de requests en la base de datos.

Solution 1 - Clean old requests:

DELETE FROM requests WHERE timestamp < date('now', '-30 days');

Solution 2 - Crear nuevo project:

  • Export important data
  • Create fresh project
  • Import only needed data

Can't Stop Server

Problem: make stop doesn't work

Solution 1 - API shutdown:

curl -X POST http://localhost:5000/api/shutdown

Solution 2 - Find and kill:

ps aux | grep main.py
kill <PID>

Nota: Esto detiene el backend. La ventana de la app de escritorio es un proceso aparte: ciérrala normalmente.

Solution 3 - Force kill:

pkill -9 -f "python.*main.py"
pkill -9 -f mitmproxy

Obtener Ayuda

If puedes't solve your issue:

  1. Check logs: Look at terminal output when starting
  2. Search issues: https://github.com/Glitchboi-sudo/Blackwire/issues
  3. Create issue: Proporciona:
    • OS and version
    • Python version
    • Mensaje de error completo
    • Pasos para reproducir
    • Logs

Consejos de Rendimiento

Consultas Lentas de Base de Datos

Blackwire ya crea índices sobre requests (timestamp, status, scope, saved, type, id) al inicializar la base de datos, así que normalmente no necesitas añadirlos a mano.

Solution 1 - Índices adicionales (si filtras mucho por host):

CREATE INDEX IF NOT EXISTS idx_requests_host ON requests(url);

Solution 2 - Enable Modo WAL:

PRAGMA journal_mode=WAL;

Carga Lenta de Extensiones

Verificar: Demasiadas extensiones habilitadas.

Solución: Deshabilitar las extensiones no usadas. Tras el cambio, make restart.


Clone this wiki locally