# Risoluzione dei problemi

> Soluzioni ai problemi più comuni di DuckLocal: comando ducklocal non trovato, file che non vengono collegati, database che non si aprono, query bloccate, S3 e dashboard.

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

Trova il sintomo, leggi la causa e applica la soluzione. Se il tuo problema non è
elencato, [apri una issue](https://github.com/JetSquirrel/DuckLocal/issues) con i
dettagli su cosa hai fatto e cosa è successo.

## Installazione e avvio

| Sintomo | Causa e soluzione |
| --- | --- |
| L'app non si apre su un Mac Intel | La release per macOS è compilata solo per Apple silicon. [Compila dai sorgenti](development.md#build-and-run) su Intel |
| Le scorciatoie di questa documentazione non fanno nulla su Windows o Linux | Leggi **Ctrl** al posto di **⌘**: ⌘↵ lì è Ctrl+Invio |
| `ducklocal: command not found` | L'immagine disco installa l'app, non un comando. [Collega il binario al tuo PATH](getting-started.md#add-command) |
| Il terminale resta occupato mentre la finestra è aperta | Aprire la GUI da un terminale la esegue in primo piano. Avviala invece da Applicazioni, oppure lascia quel terminale occupato dalla GUI |
| La cronologia, le impostazioni o i file ricordati smettono di essere salvati | Un secondo DuckLocal è in esecuzione e tiene il file dei dati dell'app. Chiudi l'altro e riavvia |
| **DuckLocal è terminato in modo imprevisto l'ultima volta** | È andato in crash e ha salvato un rapporto nella cartella dei log. Fai clic su **Mostra rapporto** e allega il rapporto a una [issue](https://github.com/JetSquirrel/DuckLocal/issues) — vedi [dove sono memorizzate le cose](settings-and-data.md#where-things-are-stored) |
| **Controllo aggiornamenti non riuscito** | Passa il mouse sopra per vedere il motivo: offline, un proxy, o un download che non corrispondeva al suo checksum. Fai clic per riprovare, oppure scarica la release da GitHub — vedi [Controllo degli aggiornamenti](settings-and-data.md#update-check) |

## Apertura dei dati

| Sintomo | Causa e soluzione |
| --- | --- |
| `File not found` su un percorso che hai indicato | Il percorso non esiste, oppure è relativo a una directory diversa da quella che pensi. Usa un percorso assoluto per essere sicuro |
| Una cartella non segnala file di dati | Nulla al suo interno corrispondeva a `.csv`, `.tsv`, `.txt`, `.parquet`, `.json`, `.ndjson`, `.jsonl`, `.xlsx`, `.xls`, `.xlsb` o `.ods` |
| Una cartella ha prodotto meno file del previsto | Le voci nascoste e i symlink vengono saltati, e una richiesta di apertura collega al massimo 256 file. Apri le sottocartelle separatamente |
| Un percorso è stato aperto come database inaspettatamente | Qualsiasi file esistente che non è un file di dati viene trattato come database DuckDB. Se non si apre, DuckLocal dice perché; all'avvio ricade sulla memoria. Vedi [Aprire un database](#opening-a-database) |
| **Non collegato …: il database ha già una tabella o una vista chiamata …** | Il database contiene già una tabella o una vista con lo stesso nome del file ricordato. DuckLocal non la sostituisce mai. Rinomina o elimina una delle due, oppure rimuovi il file da **File locali** e riaprilo per ottenere un nuovo nome |
| **Impossibile ripristinare il percorso relativo …** | Un file era ricordato tramite un percorso relativo, che non si può risolvere in una nuova sessione. Rimuovilo da **File locali** e riaprilo |
| Una vista mostra `sales_2` invece di `sales` | Un altro file o una tabella aveva già quel nome, quindi la nuova ha ricevuto un suffisso |
| La vista di un file è obsoleta | Le viste leggono il file a ogni query. Se le colonne di un CSV hanno cambiato forma, usa **Aggiorna schema** nella barra laterale |

## Aprire un database {#opening-a-database}

| Sintomo | Causa e soluzione |
| --- | --- |
| Il messaggio dice che il database è stato creato da un DuckDB più recente | Il file usa un formato di archiviazione più recente di quello che il DuckDB integrato in DuckLocal sa leggere. Esegui le righe `ATTACH … COPY FROM DATABASE` del messaggio nel DuckDB che ha creato il file, poi apri la copia. Vedi [Quando un database non si apre](data-sources.md#when-a-database-will-not-open) |
| Il messaggio dice che il database viene da DuckDB v0.9 o precedente | Esegui `EXPORT DATABASE 'dir'` con il DuckDB che l'ha scritto, poi `IMPORT DATABASE 'dir'` in DuckLocal |
| Il messaggio dice che è un database SQLite | Collegalo con **Apri → Collega database…** invece di aprirlo |
| Il messaggio dice che il file non è un database DuckDB | La sua estensione non è una di quelle che DuckLocal legge come dati, quindi è stato provato come database. Dagli un'[estensione supportata](data-sources.md#supported-file-formats), oppure leggilo in SQL, per esempio `SELECT * FROM read_csv('export.dat')` |
| DuckDB dice che non è riuscito a impostare un lock sul file | Un altro programma — un altro DuckDB, uno script, una seconda app — ha il database aperto in scrittura, e DuckDB lascia che un solo processo scriva un file. Chiudilo lì, poi apri di nuovo il file |
| DuckDB dice permesso negato | Il tuo account non può leggere il file, o non può scriverlo: il database principale viene aperto in scrittura. Sistema i permessi del file, oppure collegalo con **Sola lettura** selezionato |
| L'apertura di un database è fallita e nulla è cambiato | È previsto mentre DuckLocal è in esecuzione: un'apertura fallita lascia lo spazio di lavoro che avevi. Leggi la notifica per il motivo |
| Il tooltip della barra di stato dice **leggibile da DuckDB v1.x+** e un collega non riesce ad aprire il file | Il suo DuckDB è più vecchio di quella versione. Deve aggiornare, oppure copi tu il file con uno `STORAGE_VERSION` più vecchio — vedi [Quale DuckDB può leggere un database](data-sources.md#storage-version) |

## Database collegati

| Sintomo | Causa e soluzione |
| --- | --- |
| Un database collegato manca dopo un riavvio | Il suo file non era al percorso ricordato all'avvio, quindi è stato saltato. La registrazione resta; rimetti il file a posto e torna con la prossima connessione |
| **Questo database è già aperto, come …** | Il file è già il database principale, oppure è collegato con quel nome. Interrogalo con quel nome |
| **Impossibile collegare …: il nome … è già usato nel database aperto.** | Qualcos'altro nella connessione usa già l'alias ricordato — per esempio un database che hai collegato in SQL con lo stesso nome. Fai `DETACH` di quello, poi riapri il database o riavvia |
| La scrittura su un database collegato fallisce | È stato collegato in sola lettura, il valore predefinito. **Scollega database** dalla barra laterale, poi collegalo di nuovo con **Sola lettura** deselezionato |
| Il collegamento ha creato un database vuoto | Con **Sola lettura** deselezionato, un percorso DuckDB che non esiste viene creato. Scollegalo, elimina il file vuoto e controlla il percorso |
| Un nome di tabella senza database trova la tabella sbagliata | I nomi senza database si risolvono nel database predefinito. Fai clic destro su un database e scegli **Usa come database predefinito**, oppure scrivi `alias.table` |

## Finder e Quick Look

Questi valgono solo per macOS.

| Sintomo | Causa e soluzione |
| --- | --- |
| Il doppio clic su un file `.parquet` o `.duckdb` apre un'altra app | Quell'app è già la predefinita. Nel Finder, **Ottieni informazioni → Apri con**, scegli DuckLocal, poi **Cambia tutto…** |
| Il doppio clic su un file CSV o Excel non apre DuckLocal | Per scelta: DuckLocal non se ne assume la gestione. Usa **Apri con → DuckLocal**, oppure trascina il file sull'icona del Dock |
| DuckLocal non è offerto in **Apri con**, oppure Spazio non mostra l'anteprima di DuckLocal | macOS non ha ancora registrato l'app. Spostala in Applicazioni e avviala una volta. Per l'anteprima, poi esegui `qlmanage -r` nel Terminale e controlla che **Anteprima DuckLocal** sia attiva sotto Quick Look nelle impostazioni delle estensioni di Impostazioni di Sistema |
| Un file `.json` semplice o un file Excel non mostra l'anteprima di DuckLocal | Per scelta: quelli sono lasciati alle anteprime di macOS. I file `.jsonl` e `.ndjson` hanno l'anteprima |
| L'anteprima mostra solo 50 righe | Per scelta: un'anteprima non scansiona mai il file intero. Apri il file in DuckLocal per il resto |
| L'anteprima di un file `.duckdb` mostra un errore | L'anteprima legge il file con il DuckDB di DuckLocal, quindi un file di un DuckDB più recente fallisce anche lì. Vedi [Aprire un database](#opening-a-database) |

## Esecuzione delle query

| Sintomo | Causa e soluzione |
| --- | --- |
| **Esegui** non fa nulla | Una query è già in esecuzione. Premi **Interrompi** accanto a Esegui, o **⌘.**, per interromperla |
| Una query è fallita con `Interrupted` | Qualcuno ha premuto **Interrompi** (o ⌘.) mentre era in esecuzione. Eseguila di nuovo |
| Parte del mio SQL ha una sottolineatura ondulata rossa | L'ultima esecuzione è fallita lì. Leggi il messaggio *Query non riuscita*; il segno si cancella all'esecuzione successiva |
| **⌘↵** mostra l'editor invece di eseguire | Nella schermata del primo avvio, ⌘↵ significa "dammi un editor". Premilo di nuovo per eseguire |
| I risultati si fermano prima con un avviso di troncamento | È stato raggiunto il limite di 100.000 righe o di 2.000.000 di celle. Restringi la query; non c'è paginazione |
| I timestamp sembrano spostati | La griglia mostra i timestamp in UTC, non nell'ora locale |
| Un valore `TIMETZ` ha perso il suo offset, o un valore `BIT` o `BIGNUM` sembra fatto di byte | Quei tipi non si distinguono dai valori normali nel loro percorso verso DuckLocal. `CAST(column AS VARCHAR)` in SQL mostra il valore reale |
| L'ordinamento non porta righe oltre l'anteprima | L'ordinamento dell'intestazione riordina solo le righe caricate. Usa `ORDER BY` in SQL per ordinare il risultato completo prima del troncamento |
| Una query richiede un'estensione non installata | Le estensioni mancanti non vengono più scaricate automaticamente. Installala esplicitamente nella scheda **Estensioni**, poi caricala o riesegui la query |
| Una query che funzionava prima della 0.3.0 dice che un'estensione non è installata, o che una funzione non esiste | DuckLocal 0.3.0 esegue DuckDB 2.0, che conserva le estensioni installate per release. Installale di nuovo dalla scheda **Estensioni** — vedi [Estensioni](schema-and-history.md#extensions) |
| Un alias di colonna nudo come `minutes` causa un errore di parser | È una parola chiave SQL. Scrivi `AS minutes`, oppure mettilo tra virgolette: `SELECT count(*) AS "minutes" FROM events` |
| Facendo clic su una tabella o su una voce della cronologia ho cancellato il mio SQL | Quei clic sostituiscono l'intero buffer dell'editor. Usa una nuova scheda query per gli appunti |
| Un'esportazione ha sostituito un file senza avvisare | L'esportazione scrive nel percorso che indichi senza chiedere. Scegli un nuovo nome |

## S3

| Sintomo | Causa e soluzione |
| --- | --- |
| Le credenziali S3 sono state dimenticate | Per scelta valgono solo per la sessione, e aprire o cambiare un database le cancella. Configura di nuovo S3 |
| Configurare S3 fallisce offline | Il primo uso esegue `INSTALL httpfs`, che scarica l'estensione. Connettiti una volta, poi è in cache |
| Le credenziali temporanee (STS) vengono rifiutate | Non viene inviato alcun token di sessione. Usa chiavi di lunga durata — vedi [S3 e httpfs](s3.md#limitations) |
| Un bucket sembra più piccolo di quello che è | L'elenco si ferma a 1.000 voci per livello. Interroga invece con un glob come `'s3://bucket/prefix/*.parquet'` |

## Dashboard

| Sintomo | Causa e soluzione |
| --- | --- |
| Il grafico di una dashboard dice che una query deve essere in sola lettura | Una query `.dash` ha provato a scrivere (DDL, DML, `COPY`, `ATTACH`, …). Le dashboard eseguono solo istruzioni in sola lettura; sposta la preparazione nell'editor SQL |
| Un agente non ha visto i miei commenti | I commenti non vengono inviati da nessuna parte: è l'agente a doverli leggere. Chiedigli di eseguire `ducklocal comments FILE`, oppure di "risolvere i commenti su FILE" se ha la [skill ufficiale](cli.md#install-the-official-skill) |
| La risposta o la modifica di un agente non compare | La finestra segue sia lo spec sia `FILE.comments.json` entro un secondo. Uno spec che non è più valido mantiene in vista l'ultima dashboard funzionante, con il motivo sopra; apri **Mostra spec** per vedere il file |
| Un `PIVOT` in una dashboard viene rifiutato | Un `PIVOT` annidato dentro un `SELECT` o un `WITH` deve indicare i suoi valori. Elencali: `PIVOT t ON channel IN ('Web', 'Store') USING sum(revenue)`, oppure inizia la query con il `PIVOT` |

## Aspetto

| Sintomo | Causa e soluzione |
| --- | --- |
| Il tema torna a quello chiaro a ogni avvio | Il tema non viene salvato tra un avvio e l'altro; la lingua sì |
| Il testo o le icone sono troppo piccoli o troppo grandi | Usa il pulsante **Aa** nella barra del titolo, oppure ⌘+ / ⌘− / ⌘0. Vedi [Dimensione dell'interfaccia](settings-and-data.md#interface-size) |
| L'interfaccia è nella lingua sbagliata | Usa il pulsante `EN` / `中` nella barra del titolo; la scelta viene ricordata |

## Ricominciare da zero

Per cancellare la cronologia, i file ricordati, le schede aperte e le
impostazioni, chiudi DuckLocal e rimuovi la sua directory di dati dell'app:

```bash
rm -rf ~/Library/Application\ Support/DuckLocal
```

I tuoi file di dati non vengono mai toccati — vengono rimossi solo i registri di
DuckLocal. Vedi [Impostazioni e dati dell'app](settings-and-data.md) per cosa è
memorizzato lì.
