Solução de problemas
Encontre o sintoma, leia a causa e aplique a correção. Se o seu problema não está na lista, abra uma issue 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 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 |
| 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 — veja onde as coisas ficam guardadas |
| 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 |
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 |
| 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
| 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 |
| 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, 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 |
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 |
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 |
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 |
| 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 |
| 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 |
| 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/DuckLocalSeus arquivos de dados nunca são tocados — apenas os registros do próprio DuckLocal são removidos. Veja Configurações e dados do app para saber o que fica guardado ali.
