# Solución de problemas

> Soluciones a problemas habituales de DuckLocal: no se encuentra el comando ducklocal, archivos que no se adjuntan, bases de datos que no se abren, consultas atascadas, S3 y paneles.

Source: https://ducklocal.app/docs/es/troubleshooting

Encuentra el síntoma, lee la causa y aplica la solución. Si tu problema no está en la lista, [abre una incidencia](https://github.com/JetSquirrel/DuckLocal/issues) 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](development.md#build-and-run) 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](getting-started.md#add-command) |
| 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](https://github.com/JetSquirrel/DuckLocal/issues) — consulta [dónde se guardan las cosas](settings-and-data.md#where-things-are-stored) |
| **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](settings-and-data.md#update-check) |

## 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](#opening-a-database) |
| **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 {#opening-a-database}

| 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](data-sources.md#when-a-database-will-not-open) |
| 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](data-sources.md#supported-file-formats), 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](data-sources.md#storage-version) |

## 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](#opening-a-database) |

## 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](schema-and-history.md#extensions) |
| 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](s3.md#limitations) |
| 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](cli.md#install-the-official-skill) |
| 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](settings-and-data.md#interface-size) |
| 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/DuckLocal
```

Tus archivos de datos nunca se tocan: solo se eliminan los registros propios de DuckLocal. Consulta [Ajustes y datos de la app](settings-and-data.md) para saber qué se guarda ahí.
