# Solução de problemas

> Correções para problemas comuns do DuckLocal: comando ducklocal não encontrado, arquivos que não são anexados, bancos de dados que não abrem, consultas travadas, S3 e painéis.

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

Encontre o sintoma, leia a causa e aplique a correção. Se o seu problema não está na lista,
[abra uma issue](https://github.com/JetSquirrel/DuckLocal/issues) com detalhes do que você fez e do que aconteceu.

## Instalação e inicialização

| Sintoma | Causa e solução |
| --- | --- |
| O app não abre em um Mac Intel | A versão de macOS é compilada apenas para Apple silicon. [Compile a partir do código-fonte](development.md#build-and-run) no Intel |
| Os atalhos desta documentação não fazem nada no Windows ou Linux | Leia **Ctrl** onde está **⌘**: ⌘↵ é Ctrl+Enter ali |
| `ducklocal: command not found` | A imagem de disco instala o app, não um comando. [Crie um link do binário no seu PATH](getting-started.md#add-command) |
| O terminal fica ocupado enquanto a janela está aberta | Abrir a GUI pelo terminal a executa em primeiro plano. Inicie pelos Aplicativos, ou deixe aquele terminal para ela |
| O histórico, as configurações ou os arquivos lembrados param de ser salvos | Um segundo DuckLocal está rodando e segura o arquivo de dados do app. Saia do outro e inicie de novo |
| **O DuckLocal saiu inesperadamente da última vez** | Ele travou e salvou um relatório na pasta de logs. Clique em **Mostrar relatório** e anexe-o a uma [issue](https://github.com/JetSquirrel/DuckLocal/issues) — veja [onde as coisas ficam guardadas](settings-and-data.md#where-things-are-stored) |
| **Falha na verificação de atualizações** | Passe o mouse por cima para ver o motivo: sem conexão, um proxy, ou um download que não correspondia ao seu checksum. Clique para tentar de novo, ou baixe a versão pelo GitHub — veja [Verificação de atualizações](settings-and-data.md#update-check) |

## Abrindo dados

| Sintoma | Causa e solução |
| --- | --- |
| `File not found` em um caminho que você informou | O caminho não existe, ou é relativo a um diretório diferente do que você imagina. Use um caminho absoluto para ter certeza |
| Uma pasta não informa nenhum arquivo de dados | Nada dentro dela correspondia a `.csv`, `.tsv`, `.txt`, `.parquet`, `.json`, `.ndjson`, `.jsonl`, `.xlsx`, `.xls`, `.xlsb` ou `.ods` |
| Uma pasta produziu menos arquivos do que o esperado | Entradas ocultas e links simbólicos são ignorados, e um pedido de abertura anexa no máximo 256 arquivos. Abra as subpastas separadamente |
| Um caminho foi aberto como banco de dados sem você esperar | Qualquer arquivo existente que não seja um arquivo de dados é tratado como banco de dados DuckDB. Se não abrir, o DuckLocal diz por quê; na inicialização ele volta para a memória. Veja [Abrindo um banco de dados](#opening-a-database) |
| **Não anexado …: o banco de dados já tem uma tabela ou view chamada …** | O banco de dados já contém uma tabela ou view com o mesmo nome do arquivo lembrado. O DuckLocal nunca a substitui. Renomeie ou descarte uma das duas, ou remova o arquivo de **Arquivos locais** e abra de novo para obter um nome novo |
| **Não é possível restaurar o caminho relativo …** | Um arquivo foi lembrado por um caminho relativo, que não pode ser resolvido em uma sessão nova. Remova-o de **Arquivos locais** e abra de novo |
| Uma view mostra `sales_2` em vez de `sales` | Outro arquivo ou tabela já tinha aquele nome, então a nova recebeu um sufixo |
| A view de um arquivo está desatualizada | As views leem o arquivo a cada consulta. Se as colunas de um CSV mudaram de forma, use **Atualizar esquema** na barra lateral |

## Abrindo um banco de dados {#opening-a-database}

| Sintoma | Causa e solução |
| --- | --- |
| A mensagem diz que o banco de dados foi criado por um DuckDB mais recente | O arquivo usa um formato de armazenamento mais recente do que o DuckDB embutido no DuckLocal lê. Execute as linhas `ATTACH … COPY FROM DATABASE` da mensagem no DuckDB que criou o arquivo, e depois abra a cópia. Veja [Quando um banco de dados não abre](data-sources.md#when-a-database-will-not-open) |
| A mensagem diz que o banco de dados vem do DuckDB v0.9 ou anterior | Execute `EXPORT DATABASE 'dir'` com o DuckDB que o escreveu, e depois `IMPORT DATABASE 'dir'` no DuckLocal |
| A mensagem diz que é um banco de dados SQLite | Anexe-o com **Abrir → Anexar banco de dados…** em vez de abri-lo |
| A mensagem diz que o arquivo não é um banco de dados DuckDB | A extensão dele não é uma das que o DuckLocal lê como dados, então ele foi tentado como banco de dados. Dê a ele uma [extensão compatível](data-sources.md#supported-file-formats), ou leia-o em SQL, por exemplo `SELECT * FROM read_csv('export.dat')` |
| O DuckDB diz que não conseguiu definir um bloqueio no arquivo | Outro programa — outro DuckDB, um script, um segundo app — tem o banco de dados aberto para escrita, e o DuckDB permite que apenas um processo escreva em um arquivo. Feche-o lá e abra o arquivo de novo |
| O DuckDB diz que a permissão foi negada | Sua conta não pode ler o arquivo, ou não pode escrever nele: o banco de dados principal é aberto para escrita. Corrija as permissões do arquivo, ou anexe-o com **Somente leitura** marcado |
| Uma abertura de banco de dados falhou e nada mudou | É o esperado enquanto o DuckLocal está rodando: uma abertura com falha mantém o espaço de trabalho que você tinha. Leia a notificação para saber o motivo |
| A dica da barra de status diz **legível pelo DuckDB v1.x+** e um colega não consegue abrir o arquivo | O DuckDB dele é anterior a essa versão. Ele precisa atualizar, ou você copia o arquivo com um `STORAGE_VERSION` anterior — veja [Qual DuckDB consegue ler um banco de dados](data-sources.md#storage-version) |

## Bancos de dados anexados

| Sintoma | Causa e solução |
| --- | --- |
| Um banco de dados anexado desaparece depois de reiniciar | O arquivo dele não estava no caminho lembrado na inicialização, então foi ignorado. O registro é mantido; devolva o arquivo ao lugar e ele volta na próxima conexão |
| **Este banco de dados já está aberto, como …** | O arquivo já é o banco de dados principal, ou está anexado com esse nome. Consulte-o por esse nome |
| **Não foi possível anexar …: o nome … está ocupado no banco de dados aberto.** | Outra coisa na conexão já usa o alias lembrado — por exemplo, um banco de dados que você anexou em SQL com o mesmo nome. Faça `DETACH` desse e depois reabra o banco de dados ou reinicie |
| Escrever em um banco de dados anexado falha | Ele foi anexado como somente leitura, que é o padrão. Use **Desanexar banco de dados** na barra lateral e anexe de novo com **Somente leitura** desmarcado |
| Anexar criou um banco de dados vazio | Com **Somente leitura** desmarcado, um caminho DuckDB que não existe é criado. Desanexe-o, apague o arquivo vazio e confira o caminho |
| Um nome de tabela sem banco de dados encontra a tabela errada | Nomes sem banco de dados são resolvidos no banco de dados padrão. Clique com o botão direito em um banco de dados e escolha **Usar como banco de dados padrão**, ou escreva `alias.table` |

## Finder e Quick Look

Isto existe apenas no macOS.

| Sintoma | Causa e solução |
| --- | --- |
| Dar duplo clique em um arquivo `.parquet` ou `.duckdb` abre outro app | Esse app já é o padrão. No Finder, **Obter informações → Abrir com**, escolha DuckLocal e depois **Alterar tudo…** |
| Dar duplo clique em um arquivo CSV ou Excel não abre o DuckLocal | É intencional: o DuckLocal não assume esses formatos. Use **Abrir com → DuckLocal**, ou arraste o arquivo sobre o ícone do Dock |
| O DuckLocal não aparece em **Abrir com**, ou Espaço não mostra uma prévia do DuckLocal | O macOS ainda não registrou o app. Mova-o para Aplicativos e inicie uma vez. Para a prévia, execute depois `qlmanage -r` no Terminal, e confira se **DuckLocal Preview** está ativado em Quick Look, nas configurações de extensões das Configurações do Sistema |
| Um arquivo `.json` comum ou do Excel não mostra prévia do DuckLocal | É intencional: esses ficam com as prévias do próprio macOS. Arquivos `.jsonl` e `.ndjson` têm prévia |
| A prévia mostra apenas 50 linhas | É intencional: uma prévia nunca varre o arquivo inteiro. Abra o arquivo no DuckLocal para ver o resto |
| A prévia de um arquivo `.duckdb` mostra um erro | A prévia lê o arquivo com o DuckDB do próprio DuckLocal, então um arquivo de um DuckDB mais recente também falha ali. Veja [Abrindo um banco de dados](#opening-a-database) |

## Executando consultas

| Sintoma | Causa e solução |
| --- | --- |
| **Executar** não faz nada | Já há uma consulta rodando. Pressione **Parar** ao lado de Executar, ou **⌘.**, para interrompê-la |
| Uma consulta falhou com `Interrupted` | Alguém pressionou **Parar** (ou ⌘.) enquanto ela rodava. Execute de novo |
| Parte do meu SQL tem um sublinhado ondulado vermelho | A última execução falhou ali. Leia a mensagem *Consulta falhou*; a marca desaparece na próxima execução |
| **⌘↵** mostra o editor em vez de executar | Na tela de primeiro início, ⌘↵ significa "me dê um editor". Pressione de novo para executar |
| Os resultados param cedo demais com um aviso de truncamento | O limite de 100.000 linhas ou 2.000.000 de células foi atingido. Restrinja a consulta; não há paginação |
| As datas e horas parecem deslocadas | A grade renderiza datas e horas em UTC, não no horário local |
| Um valor `TIMETZ` perdeu seu deslocamento, ou um valor `BIT` ou `BIGNUM` parece bytes | Esses tipos não podem ser distinguidos de valores comuns no caminho até o DuckLocal. `CAST(column AS VARCHAR)` em SQL mostra o valor real |
| Ordenar não traz linhas além da prévia | A ordenação pelo cabeçalho apenas reordena as linhas carregadas. Use `ORDER BY` em SQL para ordenar o resultado completo antes do truncamento |
| Uma consulta precisa de uma extensão que não está instalada | Extensões faltantes não são mais baixadas automaticamente. Instale-a explicitamente na aba **Extensões**, depois carregue-a ou execute a consulta de novo |
| Uma consulta que funcionava antes da 0.3.0 diz que uma extensão não está instalada, ou que uma função não existe | O DuckLocal 0.3.0 roda o DuckDB 2.0, que mantém as extensões instaladas por versão. Instale-as de novo na aba **Extensões** — veja [Extensões](schema-and-history.md#extensions) |
| Um alias de coluna sem aspas como `minutes` provoca um erro de análise | É uma palavra-chave SQL. Escreva `AS minutes`, ou ponha entre aspas: `SELECT count(*) AS "minutes" FROM events` |
| Clicar em uma tabela ou em uma entrada do histórico apagou meu SQL | Esses cliques substituem todo o buffer do editor. Use uma aba de consulta nova para rascunhos |
| Uma exportação substituiu um arquivo sem avisar | Exportar escreve no caminho que você informa sem perguntar. Escolha um nome novo |

## S3

| Sintoma | Causa e solução |
| --- | --- |
| As credenciais de S3 foram esquecidas | Elas duram apenas a sessão, por design, e abrir ou trocar de banco de dados as apaga. Configure o S3 de novo |
| Configurar o S3 falha sem conexão | O primeiro uso executa `INSTALL httpfs`, que baixa a extensão. Conecte-se uma vez e ela fica em cache |
| Credenciais temporárias (STS) são rejeitadas | Nenhum token de sessão é enviado. Use chaves de longa duração — veja [S3 e httpfs](s3.md#limitations) |
| Um bucket parece menor do que é | A listagem para em 1.000 entradas por nível. Consulte com um glob como `'s3://bucket/prefix/*.parquet'` |

## Painéis

| Sintoma | Causa e solução |
| --- | --- |
| Um gráfico de painel diz que uma consulta precisa ser somente leitura | Uma consulta `.dash` tentou escrever (DDL, DML, `COPY`, `ATTACH`, …). Painéis executam apenas instruções somente leitura; mova a preparação para o editor SQL |
| Um agente não viu meus comentários | Comentários não são enviados para lugar nenhum: o agente precisa lê-los. Peça para ele executar `ducklocal comments FILE`, ou para "tratar os comentários de FILE" se ele tiver a [skill oficial](cli.md#install-the-official-skill) |
| A resposta ou a edição de um agente não aparece | A janela acompanha tanto a especificação quanto `FILE.comments.json` em menos de um segundo. Uma especificação que não valida mais mantém o último painel que funcionava, com o motivo acima dele; abra **Ver especificação** para ver o arquivo |
| Um `PIVOT` em um painel é rejeitado | Um `PIVOT` aninhado dentro de um `SELECT` ou de um `WITH` precisa nomear seus valores. Liste-os: `PIVOT t ON channel IN ('Web', 'Store') USING sum(revenue)`, ou comece a consulta com o `PIVOT` |

## Aparência

| Sintoma | Causa e solução |
| --- | --- |
| O tema volta para o claro a cada início | O tema não é salvo entre inícios; o idioma é |
| O texto ou os ícones estão pequenos ou grandes demais | Use o botão **Aa** na barra de título, ou ⌘+ / ⌘− / ⌘0. Veja [Tamanho da interface](settings-and-data.md#interface-size) |
| A interface está no idioma errado | Use o botão `EN` / `中` na barra de título; a escolha é lembrada |

## Começando de novo

Para limpar o histórico, os arquivos lembrados, as abas abertas e as configurações, saia do DuckLocal e
remova seu diretório de dados do app:

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

Seus arquivos de dados nunca são tocados — apenas os registros do próprio DuckLocal são removidos. Veja [Configurações e dados do app](settings-and-data.md) para saber o que fica guardado ali.
