Files

push full db

Signed-off-by: ale <ale@manalejandro.com>

2026-02-08 23:35:53 +01:00

17 KiB

Original Blame Histórico

Guía de Solución de Problemas (Troubleshooting)

Esta guía te ayudará a resolver problemas comunes al usar Classic Add-ons Archive v3.0.

⚠️ Problemas Actuales Conocidos (2026)

🦊 Firefox: No instala sin firma

Problema: Firefox Release NO permite instalar extensiones sin firmar, incluso cambiando xpinstall.signatures.required=false.

Solución rápida:

✅ Usa Firefox Developer Edition o Nightly (permiten deshabilitar firma)
✅ O carga como complemento temporal: about:debugging > "Cargar complemento temporal"
✅ O firma con AMO: ./build.sh --sign (requiere credenciales AMO)

Ver solución detallada

🎨 Chrome: Manifest no compatible

Problema: Chrome 127+ (junio 2024) bloqueó Manifest v2. Esta extensión usa v2.

Solución rápida:

✅ Usa Firefox (mejor opción, soporte v2 indefinido)
✅ O usa Microsoft Edge / Brave (soporte v2 hasta ~2025-2026)
❌ Chrome ya no soporta Manifest v2 (requiere migración a v3, no disponible aún)

Ver solución detallada

Problemas de Instalación

El icono de la extensión no aparece

Síntomas:

No veo el icono en la barra de herramientas

Soluciones:

Recargar la extensión:
- Firefox: about:debugging > Click en "Recargar"
- Chrome: chrome://extensions/ > Click en el icono de recargar ↻
Verificar que está habilitada:
- Firefox: about:addons > Extensiones > Buscar "Classic Add-ons Archive"
- Chrome: chrome://extensions/ > Buscar la extensión y verificar que el toggle está activado
Verificar manifest.json:
```
cat manifest.json | grep -A 5 browser_action
```
Debe existir la sección browser_action con iconos válidos.

Error al cargar la extensión

Error: "There was an error during installation"

Causas comunes:

manifest.json inválido
Archivos requeridos faltantes
Permisos incorrectos

Soluciones:

Validar el manifest:

# Instalar web-ext si no lo tienes
npm install -g web-ext

# Validar
web-ext lint

Verificar archivos requeridos:

ls -la manifest.json background.js
ls -la content/ca-archive.html content/ca-archive.js content/db-webext.js
ls -la skin/logo.png skin/button.png

Verificar sintaxis JSON:
- Usar herramienta online: https://jsonlint.com/
- O con python:
```
python3 -m json.tool manifest.json > /dev/null
```

Firefox: "This add-on could not be installed because it appears to be corrupt"

Solución:

Reconstruir el paquete:
```
./build.sh
```
Verificar integridad:
```
unzip -t dist/ca-archive-3.0.0.xpi
```
Si persiste, cargar sin empaquetar:
- about:debugging > Cargar complemento temporal
- Seleccionar manifest.json directamente

Firefox: "Add-on could not be installed because it is not signed" (sin poder deshabilitar firma)

Problema: Firefox Release NO permite deshabilitar la verificación de firma desde Firefox 48+.

Causa:

xpinstall.signatures.required=false NO funciona en Firefox Release
Solo funciona en versiones Developer/Nightly/ESR Unbranded

Soluciones:

Usar Firefox Developer Edition (RECOMENDADO):

# Descargar desde:
# https://www.mozilla.org/firefox/developer/

# Luego en about:config:
xpinstall.signatures.required = false

Usar Firefox Nightly:

# Descargar desde:
# https://www.mozilla.org/firefox/nightly/

# Luego en about:config:
xpinstall.signatures.required = false

Firmar en Mozilla AMO (para distribución):

# 1. Obtener credenciales:
# https://addons.mozilla.org/developers/addon/api/key/

# 2. Configurar en:
# private-keys/firefox-amo-credentials.json

# 3. Firmar:
./build.sh --sign

Carga temporal (limpia al cerrar Firefox):
- about:debugging#/runtime/this-firefox
- Click "Cargar complemento temporal"
- Seleccionar manifest.json
- ⚠️ Se desinstala al cerrar Firefox

Chrome: "Manifest version 2 is deprecated" o "not supported"

Problema: Chrome está deprecando/bloqueando Manifest v2.

Estado actual (febrero 2026):

Chrome 127+ (junio 2024): v2 deshabilitado para nuevas extensiones
Chrome 136+ (2025): v2 puede estar completamente bloqueado
Edge/Brave: Soporte extendido hasta 2025-2026

Soluciones:

Verificar versión de Chrome:
```
chrome://settings/help
```
Si Chrome < 127 (solo advertencia):
- ✅ La extensión funciona normalmente
- Ignora la advertencia de deprecación
- Instala en modo desarrollador normalmente
Si Chrome >= 127 (error de bloqueo):

Opción A: Usar navegador compatible (RECOMENDADO)
- Microsoft Edge: edge://extensions/
- Brave: brave://extensions/
- Ambos soportan Manifest v2 hasta ~2025-2026
Opción B: Usar Firefox
- Firefox soporta Manifest v2 indefinidamente
- Mejor compatibilidad con esta extensión
Opción C: Esperar Manifest v3 (no disponible aún)
- Estado: No implementado en esta extensión
- Requiere reescritura significativa:
  - Service workers en lugar de background scripts
  - Eliminar webRequestBlocking
  - Eliminar 'unsafe-eval' (conflicto con sql.js)
- Timeline: TBD
Workaround temporal (solo Chrome <140):

Algunos flags experimentales pueden ayudar:
```
chrome://flags/#enable-mv2-extension-deprecation-warnings
```
Cambiar a "Disabled" (solo retrasa advertencias, no evita bloqueo)

⚠️ IMPORTANTE:

Manifest v3 tiene limitaciones que dificultan esta extensión
sql.js requiere 'unsafe-eval' (prohibido en v3)
Posibles soluciones v3: migrar a IndexedDB en lugar de sql.js

Chrome: "Could not load manifest"

Error completo: "manifest_version" key must be 3...

Causa: Chrome 127+ bloqueando Manifest v2

Solución: Ver sección anterior "Manifest version 2 is deprecated"

Problemas con la Base de Datos

"Loading database for the first time" se queda cargando

Síntomas:

Mensaje de carga de DB sin terminar
Página en blanco

Causas:

Base de datos muy grande
Falta archivo SQLite
Error de red (si carga desde CDN)

Soluciones:

Verificar que existe el archivo DB:
```
ls -lh content/db/*.sqlite
```
Verificar tamaño de la DB:
```
du -h content/db/*.sqlite
```
Si es >50MB, puede tardar en el primer acceso.
Revisar la consola del navegador (F12 > Console):
- Buscar errores relacionados con fetch o sql.js

Limpiar storage y reintentar:

// En la consola del navegador
browser.storage.local.clear()
// o en Chrome:
chrome.storage.local.clear()

Verificar permisos del archivo:
```
chmod 644 content/db/*.sqlite
```

Error: "Could not load SQL engine"

Causa: sql.js no se pudo cargar

Soluciones:

Verificar conexión a internet (si usa CDN)

Descargar sql.js localmente:

cd content/
wget https://cdnjs.cloudflare.com/ajax/libs/sql.js/1.8.0/sql-wasm.js
wget https://cdnjs.cloudflare.com/ajax/libs/sql.js/1.8.0/sql-wasm.wasm

Actualizar rutas en db-webext.js:

// Cambiar:
locateFile: file => `https://cdnjs.cloudflare.com/ajax/libs/sql.js/1.8.0/${file}`

// Por:
locateFile: file => browser.runtime.getURL(`content/${file}`)

Agregar archivos a web_accessible_resources en manifest.json:

"web_accessible_resources": [
  "content/*.wasm",
  "content/sql-wasm.js"
]

Error: "Database has just been updated, not ready or corrupted!"

Causa: Archivo SQLite corrupto o inaccesible

Soluciones:

Verificar integridad de la DB:

sqlite3 content/db/ca-archive-*.sqlite "PRAGMA integrity_check;"

Debe retornar "ok"

Re-descargar la base de datos:
- Si tienes repositorio Git: git checkout content/db/*.sqlite
- O descargar manualmente desde releases
Permisos de lectura:
```
chmod 644 content/db/*.sqlite
```

Problemas de Navegación

Los enlaces no funcionan

Síntomas:

Click en categoría/addon no hace nada
URL no cambia
Página en blanco

Soluciones:

Verificar hash routing:
- La URL debe ser: moz-extension://[id]/content/ca-archive.html#list
- No debe ser: caa:list (eso es legacy)
Revisar consola JavaScript (F12):
- Buscar errores en ca-archive.js

Verificar que los módulos se cargan:

// En la consola del navegador
console.log(typeof List, typeof Addon, typeof DB);
// Debe mostrar los tipos de objeto/function

Limpiar caché del navegador:
- Firefox: Ctrl+Shift+Del > Marcar "Caché"
- Chrome: Ctrl+Shift+Del > "Cached images and files"

Búsqueda no funciona

Síntomas:

Campo de búsqueda no responde
No muestra resultados

Soluciones:

Verificar que la DB está cargada:
- Debe haber completado la carga inicial
- Revisar que no hay mensajes de error en consola
Verificar el formulario:
```
<form id="search" action="#list">
```
Debe tener action="#list" (no caa:list)
Probar búsqueda directa:
- Navegar manualmente a: #list?q=tu-búsqueda

Problemas de Rendimiento

La extensión es lenta

Síntomas:

Navegación lenta entre páginas
La UI se congela
Alta uso de CPU/RAM

Causas:

Base de datos muy grande en memoria
Consultas SQL no optimizadas
Demasiados addons en listado

Soluciones:

Verificar uso de memoria:
- Firefox: about:performance
- Chrome: chrome://process-internals/
Reducir resultados por página:
- Editar módulos que hacen consultas (list.js, addon.js)
- Agregar límite LIMIT a queries SQL
Considerar IndexedDB en lugar de sql.js:
- sql.js carga toda la DB en RAM
- IndexedDB maneja datos en disco de forma nativa
Cerrar otras extensiones:
- Conflictos con otras extensiones pueden causar lentitud

Carga inicial muy lenta (>30 segundos)

Causa: Base de datos grande descargándose por primera vez

Soluciones:

Paciencia: Primera carga es normal que tarde
- DB de ~50MB puede tardar 30-60s en redes lentas
Verificar progreso:
- Abrir Network tab (F12 > Network)
- Buscar descarga del archivo .sqlite

Pre-cargar la DB:

Copiar manualmente a storage:

// Demasiado complejo, mejor esperar carga natural

Usar conexión más rápida para primera instalación

Errores en la Consola

"ReferenceError: DB is not defined"

Causa: db-webext.js no se cargó antes de ca-archive.js

Solución:

Verificar orden en ca-archive.html:

<!-- CORRECTO: -->
<script src="db-webext.js"></script>
<script src="ca-archive.js"></script>

<!-- INCORRECTO: -->
<script src="ca-archive.js"></script>
<script src="db-webext.js"></script>

"Failed to load script: versions.js"

Causa: Módulo no existe o ruta incorrecta

Soluciones:

Verificar que existe:
```
ls -la content/versions.js
```
Verificar permisos:
```
chmod 644 content/*.js
```

Verificar en web_accessible_resources (manifest.json):

"web_accessible_resources": [
  "content/*.js"
]

"Unsafe attempt to load URL"

Causa: Violación de Content Security Policy

Solución:

Actualizar CSP en manifest.json:

"content_security_policy": "script-src 'self' 'unsafe-eval'; object-src 'self'"

Nota: 'unsafe-eval' es necesario para sql.js (WebAssembly).

"TypeError: Cannot read property 'openDB' of undefined"

Causa: Variable DB no está definida globalmente

Solución:

En db-webext.js, verificar al final:

if (typeof window !== "undefined") {
  window.DB = DB;
}

Incompatibilidades

No funciona en Firefox 56 o inferior

Explicación:

v3.0 requiere Firefox 57+ (WebExtensions puras)
Firefox 56 y anteriores usan sistema legacy

Solución:

Usar la versión 2.x para Firefox ≤56
O actualizar Firefox a versión moderna

No funciona en Pale Moon / Basilisk

Explicación:

Estos navegadores no soportan WebExtensions completas
Usan sistema legacy de Firefox

Solución:

Usar la versión 2.x legacy
No hay planes de portar v3 a estos navegadores

Problemas en Chrome con storage

Error: "QUOTA_BYTES quota exceeded"

Causa: Base de datos muy grande para storage.local de Chrome (límite 10MB)

Solución:

Ya incluido: Permiso unlimitedStorage en manifest.json

Verificar que está presente:

"permissions": [
  "unlimitedStorage"
]

Si sigue fallando: Considerar:
- Comprimir la DB
- Usar chunks para storage
- Usar IndexedDB nativa

Obtener Ayuda

Si ninguna solución funciona:

1. Recopilar información

Información del sistema:

Navegador y versión: about:support (Firefox) o chrome://version/ (Chrome)
Versión de la extensión: Ver manifest.json
Sistema operativo

Logs:

// En consola del navegador (F12)
console.log("Extension ID:", browser.runtime.id);
console.log("Extension URL:", browser.runtime.getURL(""));

// En consola de background script
// (about:debugging > Inspeccionar)
// Copiar todos los console.log relevantes

Errores:

Captura de pantalla de errores en consola
Texto completo de mensajes de error

2. Verificar problemas conocidos

GitHub Issues: https://github.com/JustOff/ca-archive/issues
Buscar error específico

3. Reportar bug

Si no existe issue similar, crear uno nuevo:

Plantilla:

## Descripción del problema
[Describe qué está fallando]

## Pasos para reproducir
1. [Primer paso]
2. [Segundo paso]
3. [...]

## Comportamiento esperado
[Qué debería pasar]

## Comportamiento actual
[Qué está pasando]

## Entorno
- Navegador: [Firefox 100 / Chrome 105]
- SO: [Linux / Windows / macOS]
- Versión extensión: [3.0.0]

## Logs

[Pegar logs de consola aquí]


## Capturas
[Adjuntar screenshots si aplica]

4. Contacto

GitHub Issues: https://github.com/JustOff/ca-archive/issues
Discusiones: https://github.com/JustOff/ca-archive/discussions
Email: [Especificar si aplica]

Debugging Avanzado

Habilitar logging detallado

En background.js, agregar al inicio:

const DEBUG = true;

function log(...args) {
  if (DEBUG) console.log("[CA Archive]", ...args);
}

Luego usar log() en lugar de console.log().

Inspeccionar storage

// Firefox
browser.storage.local.get(null).then(console.log);

// Chrome
chrome.storage.local.get(null, console.log);

Ejecutar queries SQL manualmente

// En consola de ca-archive.html
if (DB.db) {
  const results = DB.execute("SELECT COUNT(*) FROM addons");
  console.log(results);
}

Profiling de rendimiento

Abrir DevTools (F12)
Ir a tab "Performance" / "Rendimiento"
Click en "Record" / "Grabar"
Realizar acción lenta
Stop y analizar flamegraph

Recursos Adicionales

¿Solucionaste tu problema? ¡Considera contribuir esta solución a la documentación!

¿Problema diferente? Abre un issue en GitHub: https://github.com/JustOff/ca-archive/issues

17 KiB Original Blame Histórico

Guía de Solución de Problemas (Troubleshooting)

⚠️ Problemas Actuales Conocidos (2026)

🦊 Firefox: No instala sin firma

🎨 Chrome: Manifest no compatible

📋 Índice Completo

Problemas de Instalación

El icono de la extensión no aparece

Error al cargar la extensión

Firefox: "This add-on could not be installed because it appears to be corrupt"

Firefox: "Add-on could not be installed because it is not signed" (sin poder deshabilitar firma)

Chrome: "Manifest version 2 is deprecated" o "not supported"

Chrome: "Could not load manifest"

Problemas con la Base de Datos

"Loading database for the first time" se queda cargando

Error: "Could not load SQL engine"

Error: "Database has just been updated, not ready or corrupted!"

Problemas de Navegación

Los enlaces no funcionan

Búsqueda no funciona

Problemas de Rendimiento

La extensión es lenta

Carga inicial muy lenta (>30 segundos)

Errores en la Consola

"ReferenceError: DB is not defined"

"Failed to load script: versions.js"

"Unsafe attempt to load URL"

"TypeError: Cannot read property 'openDB' of undefined"

Incompatibilidades

No funciona en Firefox 56 o inferior

No funciona en Pale Moon / Basilisk

Problemas en Chrome con storage

Obtener Ayuda

1. Recopilar información

2. Verificar problemas conocidos

3. Reportar bug

4. Contacto

Debugging Avanzado

Habilitar logging detallado

Inspeccionar storage

Ejecutar queries SQL manualmente

Profiling de rendimiento

Recursos Adicionales

17 KiB

Original Blame Histórico