Solución de problemas
Encuentra el síntoma, lee la causa y aplica la solución. Si tu problema no está en la lista, abre una incidencia con detalles de lo que hiciste y lo que ocurrió.
Instalación y arranque
| Síntoma | Causa y solución |
|---|---|
| La app no se abre en un Mac Intel | La versión de macOS está compilada solo para Apple silicon. Compílala desde el código fuente en Intel |
| Los atajos de esta documentación no hacen nada en Windows o Linux | Lee Ctrl donde dice ⌘: ⌘↵ es Ctrl+Enter allí |
ducklocal: command not found | La imagen de disco instala la app, no un comando. Enlaza el binario en tu PATH |
| El terminal queda ocupado mientras la ventana está abierta | Abrir la GUI desde un terminal la ejecuta en primer plano. Iníciala desde Aplicaciones, o deja ese terminal para ella |
| El historial, los ajustes o los archivos recordados dejan de guardarse | Hay un segundo DuckLocal en ejecución que tiene el archivo de datos de la app. Cierra el otro y vuelve a iniciar |
| DuckLocal se cerró inesperadamente la última vez | Se bloqueó y guardó un informe en la carpeta de registros. Haz clic en Mostrar informe y adjúntalo a una incidencia — consulta dónde se guardan las cosas |
| Error al comprobar actualizaciones | Pasa el cursor por encima para ver el motivo: sin conexión, un proxy, o una descarga que no coincidía con su suma de comprobación. Haz clic para reintentar, o descarga la versión desde GitHub — consulta Comprobación de actualizaciones |
Abrir datos
| Síntoma | Causa y solución |
|---|---|
File not found en una ruta que indicaste | La ruta no existe, o es relativa a un directorio distinto del que crees. Usa una ruta absoluta para asegurarte |
| Una carpeta no informa de archivos de datos | Nada dentro coincidía con .csv, .tsv, .txt, .parquet, .json, .ndjson, .jsonl, .xlsx, .xls, .xlsb ni .ods |
| Una carpeta produjo menos archivos de los esperados | Se omiten las entradas ocultas y los enlaces simbólicos, y una solicitud de apertura adjunta como máximo 256 archivos. Abre las subcarpetas por separado |
| Una ruta se abrió como base de datos sin esperarlo | Cualquier archivo existente que no sea un archivo de datos se trata como base de datos DuckDB. Si no se abre, DuckLocal dice por qué; al arrancar, recurre a la memoria. Consulta Abrir una base de datos |
| No se adjuntó …: la base de datos ya tiene una tabla o vista llamada … | La base de datos ya contiene una tabla o vista con el mismo nombre que el archivo recordado. DuckLocal nunca la reemplaza. Renombra o elimina una de las dos, o quita el archivo de Archivos locales y ábrelo de nuevo para obtener un nombre nuevo |
| No se puede restaurar la ruta relativa … | Un archivo se recordó con una ruta relativa, que no se puede resolver en una sesión nueva. Quítalo de Archivos locales y ábrelo otra vez |
Una vista muestra sales_2 en lugar de sales | Otro archivo o tabla ya tenía ese nombre, así que la nueva recibió un sufijo |
| La vista de un archivo está desactualizada | Las vistas leen el archivo en cada consulta. Si las columnas de un CSV cambiaron de forma, usa Actualizar esquema en la barra lateral |
Abrir una base de datos
| Síntoma | Causa y solución |
|---|---|
| El mensaje dice que la base de datos la creó un DuckDB más reciente | El archivo usa un formato de almacenamiento más reciente que el que lee el DuckDB integrado en DuckLocal. Ejecuta las líneas ATTACH … COPY FROM DATABASE del mensaje en el DuckDB que creó el archivo, y luego abre la copia. Consulta Cuando una base de datos no se abre |
| El mensaje dice que la base de datos viene de DuckDB v0.9 o anterior | Ejecuta EXPORT DATABASE 'dir' con el DuckDB que la escribió, y luego IMPORT DATABASE 'dir' en DuckLocal |
| El mensaje dice que es una base de datos SQLite | Adjúntala con Abrir → Adjuntar base de datos… en lugar de abrirla |
| El mensaje dice que el archivo no es una base de datos DuckDB | Su extensión no es una de las que DuckLocal lee como datos, así que se intentó como base de datos. Dale una extensión compatible, o léelo en SQL, por ejemplo SELECT * FROM read_csv('export.dat') |
| DuckDB dice que no pudo establecer un bloqueo en el archivo | Otro programa —otro DuckDB, un script, una segunda app— tiene la base de datos abierta para escritura, y DuckDB solo permite que un proceso escriba en un archivo. Ciérrala allí y vuelve a abrir el archivo |
| DuckDB dice que se denegó el permiso | Tu cuenta no puede leer el archivo, o no puede escribir en él: la base de datos principal se abre para escritura. Corrige los permisos del archivo, o adjúntala con Solo lectura marcado |
| Una apertura de base de datos falló y nada cambió | Es lo esperado mientras DuckLocal está en ejecución: una apertura fallida deja el espacio de trabajo que tenías. Lee la notificación para ver el motivo |
| La descripción emergente de la barra de estado dice legible por DuckDB v1.x+ y un compañero no puede abrir el archivo | Su DuckDB es anterior a esa versión. Tiene que actualizar, o tú puedes copiar el archivo con un STORAGE_VERSION anterior — consulta Qué DuckDB puede leer una base de datos |
Bases de datos adjuntas
| Síntoma | Causa y solución |
|---|---|
| Una base de datos adjunta falta tras reiniciar | Su archivo no estaba en la ruta recordada al arrancar, así que se omitió. El registro se conserva; devuelve el archivo a su sitio y volverá con la próxima conexión |
| Esta base de datos ya está abierta, como … | El archivo ya es la base de datos principal, o está adjunto con ese nombre. Consúltalo con ese nombre |
| No se pudo adjuntar …: el nombre … está ocupado en la base de datos abierta. | Otra cosa de la conexión ya usa el alias recordado; por ejemplo, una base de datos que adjuntaste en SQL con el mismo nombre. Haz DETACH de esa y luego vuelve a abrir la base de datos o reinicia |
| Escribir en una base de datos adjunta falla | Se adjuntó en modo de solo lectura, que es lo predeterminado. Usa Desadjuntar base de datos en la barra lateral y adjúntala de nuevo con Solo lectura desmarcado |
| Al adjuntar se creó una base de datos vacía | Con Solo lectura desmarcado, se crea una ruta DuckDB que no existe. Desadjúntala, borra el archivo vacío y revisa la ruta |
| Un nombre de tabla sin base de datos encuentra la tabla equivocada | Los nombres sin base de datos se resuelven en la base de datos predeterminada. Haz clic derecho en una base de datos y elige Usar como base de datos predeterminada, o escribe alias.table |
Finder y Quick Look
Estos solo existen en macOS.
| Síntoma | Causa y solución |
|---|---|
Hacer doble clic en un archivo .parquet o .duckdb abre otra app | Esa app ya es la predeterminada. En Finder, Obtener información → Abrir con, elige DuckLocal y luego Cambiar todo… |
| Hacer doble clic en un archivo CSV o Excel no abre DuckLocal | Es intencionado: DuckLocal no se hace cargo de esos formatos. Usa Abrir con → DuckLocal, o suelta el archivo sobre el icono del Dock |
| DuckLocal no aparece en Abrir con, o Espacio no muestra una vista previa de DuckLocal | macOS aún no ha registrado la app. Muévela a Aplicaciones e iníciala una vez. Para la vista previa, ejecuta después qlmanage -r en Terminal, y comprueba que Vista previa de DuckLocal está activada en Quick Look, en los ajustes de extensiones de Ajustes del Sistema |
Un archivo .json normal o de Excel no muestra vista previa de DuckLocal | Es intencionado: se dejan a las vistas previas propias de macOS. Los archivos .jsonl y .ndjson sí tienen vista previa |
| La vista previa muestra solo 50 filas | Es intencionado: una vista previa nunca recorre el archivo entero. Abre el archivo en DuckLocal para ver el resto |
La vista previa de un archivo .duckdb muestra un error | La vista previa lee el archivo con el DuckDB propio de DuckLocal, así que un archivo de un DuckDB más reciente también falla ahí. Consulta Abrir una base de datos |
Ejecutar consultas
| Síntoma | Causa y solución |
|---|---|
| Ejecutar no hace nada | Ya hay una consulta en ejecución. Pulsa Detener junto a Ejecutar, o ⌘., para interrumpirla |
Una consulta falló con Interrupted | Alguien pulsó Detener (o ⌘.) mientras se ejecutaba. Vuelve a ejecutarla |
| Parte de mi SQL tiene un subrayado ondulado rojo | La última ejecución falló ahí. Lee el mensaje Consulta fallida; la marca desaparece en la siguiente ejecución |
| ⌘↵ muestra el editor en lugar de ejecutar | En la pantalla de primer inicio, ⌘↵ significa "dame un editor". Pulsa otra vez para ejecutar |
| Los resultados se cortan antes con un aviso de truncamiento | Se alcanzó el límite de 100.000 filas o 2.000.000 de celdas. Acota la consulta; no hay paginación |
| Las marcas de tiempo parecen desplazadas | La cuadrícula muestra las marcas de tiempo en UTC, no en hora local |
Un valor TIMETZ ha perdido su desplazamiento, o un valor BIT o BIGNUM parece bytes | Esos tipos no se pueden distinguir de valores normales de camino a DuckLocal. CAST(column AS VARCHAR) en SQL muestra el valor real |
| Ordenar no trae filas más allá de la vista previa | Ordenar por la cabecera solo reordena las filas cargadas. Usa ORDER BY en SQL para ordenar el resultado completo antes del truncamiento |
| Una consulta necesita una extensión que no está instalada | Las extensiones que faltan ya no se descargan automáticamente. Instálala explícitamente en la pestaña Extensiones, y luego cárgala o vuelve a ejecutar la consulta |
| Una consulta que funcionaba antes de la 0.3.0 dice que una extensión no está instalada, o que una función no existe | DuckLocal 0.3.0 ejecuta DuckDB 2.0, que guarda las extensiones instaladas por versión. Instálalas otra vez desde la pestaña Extensiones — consulta Extensiones |
Un alias de columna sin comillas como minutes provoca un error de análisis | Es una palabra clave de SQL. Escribe AS minutes, o entrecomíllalo: SELECT count(*) AS "minutes" FROM events |
| Hacer clic en una tabla o en una entrada del historial borró mi SQL | Esos clics reemplazan todo el búfer del editor. Usa una pestaña de consulta nueva para pruebas |
| Una exportación reemplazó un archivo sin avisar | Exportar escribe en la ruta que indicas sin preguntar. Elige un nombre nuevo |
S3
| Síntoma | Causa y solución |
|---|---|
| Las credenciales de S3 se olvidaron | Duran solo la sesión por diseño, y abrir o cambiar de base de datos las borra. Configura S3 otra vez |
| Configurar S3 falla sin conexión | El primer uso ejecuta INSTALL httpfs, que descarga la extensión. Conéctate una vez y quedará en caché |
| Se rechazan las credenciales temporales (STS) | No se envía ningún token de sesión. Usa claves de larga duración — consulta S3 y httpfs |
| Un bucket parece más pequeño de lo que es | El listado se detiene en 1000 entradas por nivel. Consulta con un glob como 's3://bucket/prefix/*.parquet' |
Paneles
| Síntoma | Causa y solución |
|---|---|
| Un gráfico de un panel dice que una consulta debe ser de solo lectura | Una consulta .dash intentó escribir (DDL, DML, COPY, ATTACH, …). Los paneles solo ejecutan sentencias de solo lectura; mueve la preparación al editor SQL |
| Un agente no vio mis comentarios | Los comentarios no se envían a ningún sitio: el agente tiene que leerlos. Pídele que ejecute ducklocal comments FILE, o que "atienda los comentarios de FILE" si tiene la habilidad oficial |
| La respuesta o la edición de un agente no aparece | La ventana sigue tanto la especificación como FILE.comments.json en menos de un segundo. Una especificación que ya no valida mantiene el último panel que funcionaba, con el motivo encima; abre Ver especificación para ver el archivo |
Se rechaza un PIVOT en un panel | Un PIVOT anidado dentro de un SELECT o un WITH debe nombrar sus valores. Enuméralos: PIVOT t ON channel IN ('Web', 'Store') USING sum(revenue), o empieza la consulta con el PIVOT |
Apariencia
| Síntoma | Causa y solución |
|---|---|
| El tema vuelve a claro en cada inicio | El tema no se guarda entre inicios; el idioma sí |
| El texto o los iconos son demasiado pequeños o grandes | Usa el botón Aa de la barra de título, o ⌘+ / ⌘− / ⌘0. Consulta Tamaño de la interfaz |
| La interfaz está en el idioma equivocado | Usa el botón EN / 中 de la barra de título; la elección se recuerda |
Empezar de cero
Para borrar el historial, los archivos recordados, las pestañas abiertas y los ajustes, cierra DuckLocal y elimina su directorio de datos de la app:
bash
rm -rf ~/Library/Application\ Support/DuckLocalTus archivos de datos nunca se tocan: solo se eliminan los registros propios de DuckLocal. Consulta Ajustes y datos de la app para saber qué se guarda ahí.
