Ir al contenido

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íntomaCausa y solución
La app no se abre en un Mac IntelLa 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 LinuxLee Ctrl donde dice ⌘: ⌘↵ es Ctrl+Enter allí
ducklocal: command not foundLa imagen de disco instala la app, no un comando. Enlaza el binario en tu PATH
El terminal queda ocupado mientras la ventana está abiertaAbrir 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 guardarseHay 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 vezSe 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 actualizacionesPasa 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íntomaCausa y solución
File not found en una ruta que indicasteLa 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 datosNada dentro coincidía con .csv, .tsv, .txt, .parquet, .json, .ndjson, .jsonl, .xlsx, .xls, .xlsb ni .ods
Una carpeta produjo menos archivos de los esperadosSe 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 esperarloCualquier 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 salesOtro archivo o tabla ya tenía ese nombre, así que la nueva recibió un sufijo
La vista de un archivo está desactualizadaLas 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íntomaCausa y solución
El mensaje dice que la base de datos la creó un DuckDB más recienteEl 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 anteriorEjecuta 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 SQLiteAdjúntala con Abrir → Adjuntar base de datos… en lugar de abrirla
El mensaje dice que el archivo no es una base de datos DuckDBSu 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 archivoOtro 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 permisoTu 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 archivoSu 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íntomaCausa y solución
Una base de datos adjunta falta tras reiniciarSu 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 fallaSe 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íaCon 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 equivocadaLos 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íntomaCausa y solución
Hacer doble clic en un archivo .parquet o .duckdb abre otra appEsa 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 DuckLocalEs 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 DuckLocalmacOS 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 DuckLocalEs 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 filasEs 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 errorLa 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íntomaCausa y solución
Ejecutar no hace nadaYa hay una consulta en ejecución. Pulsa Detener junto a Ejecutar, o ⌘., para interrumpirla
Una consulta falló con InterruptedAlguien pulsó Detener (o ⌘.) mientras se ejecutaba. Vuelve a ejecutarla
Parte de mi SQL tiene un subrayado ondulado rojoLa última ejecución falló ahí. Lee el mensaje Consulta fallida; la marca desaparece en la siguiente ejecución
⌘↵ muestra el editor en lugar de ejecutarEn la pantalla de primer inicio, ⌘↵ significa "dame un editor". Pulsa otra vez para ejecutar
Los resultados se cortan antes con un aviso de truncamientoSe 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 desplazadasLa 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 bytesEsos 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 previaOrdenar 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á instaladaLas 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 existeDuckLocal 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álisisEs 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 SQLEsos clics reemplazan todo el búfer del editor. Usa una pestaña de consulta nueva para pruebas
Una exportación reemplazó un archivo sin avisarExportar escribe en la ruta que indicas sin preguntar. Elige un nombre nuevo

S3 ​

SíntomaCausa y solución
Las credenciales de S3 se olvidaronDuran 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ónEl 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 esEl listado se detiene en 1000 entradas por nivel. Consulta con un glob como 's3://bucket/prefix/*.parquet'

Paneles ​

SíntomaCausa y solución
Un gráfico de un panel dice que una consulta debe ser de solo lecturaUna 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 comentariosLos 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 apareceLa 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 panelUn 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íntomaCausa y solución
El tema vuelve a claro en cada inicioEl tema no se guarda entre inicios; el idioma sí
El texto o los iconos son demasiado pequeños o grandesUsa el botón Aa de la barra de título, o ⌘+ / ⌘− / ⌘0. Consulta Tamaño de la interfaz
La interfaz está en el idioma equivocadoUsa 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/DuckLocal

Tus 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í.

Publicado bajo la licencia Apache-2.0.