🛠️ Solução de Problemas#

Guia de diagnóstico técnico (comandos, logs, causas) para os problemas mais comuns. Para respostas rápidas em formato pergunta-resposta, veja também a FAQ.

Índice#

O Codis não abre / tela preta
Erro: "No module named tkinter"
Fontes distorcidas ou ilegíveis
Tela em branco no Linux (Wayland)
Antivírus bloqueia o executável
LSP não funciona / sem autocomplete
Editor muito lento em arquivos grandes
Git panel mostra "git não encontrado"
Terminal integrado não abre (Windows)
Erro de encoding ao abrir arquivo
Plugins não carregam
Configurações corrompidas / reset
Coletar informações para reportar bug

O Codis não abre / tela preta#

Sintomas: Processo Python inicia e termina sem abrir janela, ou janela aparece vazia/preta.

Diagnóstico:

# Execute pelo terminal para ver erros
python run.py

# Com log detalhado
CODIS_DEBUG=1 python run.py

Causas comuns:

Python < 3.12 - o Codis usa f-strings com aspas aninhadas (PEP 701), sintaxe válida apenas em 3.12+.
```
python --version   # deve ser 3.12.x ou superior
```
Tkinter não instalado - veja a seção Erro: "No module named tkinter".
Configuração corrompida - veja Configurações corrompidas / reset.
Conflito de display no Linux - veja Tela em branco no Linux (Wayland).

Erro: "No module named tkinter"#

O Tkinter não está incluído em algumas instalações Python, especialmente no Linux.

Ubuntu / Debian:

sudo apt install python3-tk

Fedora / RHEL:

sudo dnf install python3-tkinter

Arch Linux:

sudo pacman -S tk

macOS (via Homebrew):

brew install python-tk@3.12

Windows: O instalador oficial do Python inclui Tkinter por padrão. Se estiver faltando, reinstale Python com a opção "tcl/tk and IDLE" marcada.

Fontes distorcidas ou ilegíveis#

Linux: Instale as fontes DejaVu e configure o fontconfig:

sudo apt install fonts-dejavu-core fonts-dejavu-extra fontconfig
fc-cache -fv

Windows: Certifique-se de que ClearType está ativado:

Configurações → Personalização → Fontes → Configurações de ClearType

macOS: Fontes borradas em telas não-Retina são uma limitação do Tkinter no macOS. Use Configurações → Editor → Fonte e escolha uma fonte com hinting manual (ex: Menlo, Courier New).

Todas as plataformas: Em Configurações → Aparência → Escala de Interface, ajuste o DPI multiplier para corresponder à sua tela.

Tela em branco no Linux (Wayland)#

O Tkinter usa X11. No Wayland, é necessário o XWayland.

Verificar se XWayland está disponível:

echo $WAYLAND_DISPLAY   # deve mostrar wayland-0 ou similar
echo $DISPLAY           # deve mostrar :0 ou similar (XWayland)

Forçar X11:

GDK_BACKEND=x11 python run.py

GNOME (Wayland): Instale xwayland se não estiver presente:

sudo apt install xwayland   # Ubuntu/Debian

KDE (Wayland): XWayland é instalado por padrão com o Plasma. Se não estiver funcionando:

sudo apt install kwin-wayland-backend-x11

Antivírus bloqueia o executável#

Executáveis gerados por PyInstaller frequentemente disparam falsos positivos em antivírus heurísticos. Isso afeta especialmente binários Windows.

Antivírus comuns afetados: Windows Defender, Bkav, Gridinsoft, SentinelOne, Skyhigh.

Causa: O bootstrap do PyInstaller (código que carrega o Python runtime) tem padrões comportamentais similares a droppers. Não há malware no Codis.

Soluções:

Adicionar exceção no antivírus - adicione a pasta do Codis como exceção/exclusão.

Verificar integridade - os hashes SHA-256 dos binários oficiais estão em cada GitHub Release:

# Windows (PowerShell)
Get-FileHash Codis.exe -Algorithm SHA256

# Linux / macOS
sha256sum Codis

Executar pelo Python - a opção mais segura para quem desconfia do binário:

git clone https://github.com/KillovSky/Codis.git
pip install -r requirements.txt
python run.py

Reportar falso positivo - submeta o binário para análise no VirusTotal e reporte como falso positivo diretamente ao seu antivírus.

LSP não funciona / sem autocomplete#

Verificar se o servidor LSP está instalado:

# Para Python
pylsp --version   # ou: python-language-server --version

# Instalar
pip install python-lsp-server[all]

Verificar configuração:

Abra Configurações → LSP → Servidores
Confirme que o caminho do servidor está correto
Clique em "Testar Conexão"

Log do LSP:

CODIS_DEBUG=1 python run.py 2>&1 | grep -i lsp

Problemas comuns:

Sintoma	Causa	Solução
"LSP: servidor não encontrado"	`pylsp` não está no PATH	`pip install python-lsp-server[all]`
"LSP: timeout na inicialização"	Servidor lento para iniciar	Aumentar timeout em Configurações → LSP
Autocomplete funciona mas hover não	Capacidade não suportada pelo servidor	Normal para alguns servidores LSP
LSP trava ao abrir arquivo grande	Análise estática pesada	Desativar LSP para arquivos > X KB em Configurações

Editor muito lento em arquivos grandes#

O Codis ativa automaticamente o modo arquivo grande para arquivos com mais de 500 KB. Se não estiver ocorrendo:

Abra Configurações → Performance
Reduza large_file_threshold_kb (padrão: 500)
Desative minimap_enabled para arquivos grandes
Desative animations_enabled

Para arquivos extremamente grandes (> 50 MB), recomendamos usar less ou vim no terminal integrado do Codis.

Git panel mostra "git não encontrado"#

Linux / macOS:

which git   # deve mostrar /usr/bin/git ou similar
# Se não encontrado:
sudo apt install git    # Ubuntu/Debian
brew install git        # macOS

Windows: Instale o Git for Windows e certifique-se de que está no PATH:

where git

Se o Git está instalado mas o Codis não encontra, configure o caminho manualmente:

Configurações → Git → Caminho do executável git

Terminal integrado não abre (Windows)#

O terminal integrado no Windows usa pywinpty para suporte a PTY completo.

pip install pywinpty

Se pywinpty não estiver disponível, o terminal cai para modo subprocess simples (sem cores ANSI, sem interatividade completa). Isso é esperado - o editor ainda funciona.

Alternativa: Use o PowerShell ou CMD externo via Ferramentas → Abrir terminal externo.

Erro de encoding ao abrir arquivo#

O Codis detecta encoding automaticamente via charset-normalizer ou chardet. Se não estiver instalado:

pip install charset-normalizer chardet

Para forçar encoding manualmente ao abrir um arquivo:

Clique com o botão direito no arquivo na file tree
Abrir com encoding → escolha o encoding

Ou via menu Arquivo → Reabrir com encoding.

Plugins não carregam#

Verificar log de plugins:

CODIS_DEBUG=1 python run.py 2>&1 | grep -i plugin

Causas comuns:

Erro de sintaxe no plugin - o plugin tem um bug que impede o carregamento. Verifique o log.
Dependência faltando - o plugin requer um pacote não instalado. Veja a documentação do plugin.
Versão incompatível - o plugin foi escrito para uma versão anterior do Codis. Verifique a versão mínima exigida.

Desativar todos os plugins temporariamente:

CODIS_NO_PLUGINS=1 python run.py

Configurações corrompidas / reset#

As configurações ficam em ~/.codis/config.json.

Resetar para padrão:

# Backup
cp ~/.codis/config.json ~/.codis/config.json.bak

# Reset
rm ~/.codis/config.json
python run.py   # recria com valores padrão

Windows: A pasta fica em %USERPROFILE%\.codis\.

Editar manualmente (para usuários avançados):

# O arquivo é JSON padrão - editável em qualquer editor de texto
nano ~/.codis/config.json

Coletar informações para reportar bug#

Antes de abrir uma issue, colete:

# Versão do Python e Tkinter
python -c "import sys, tkinter; print(sys.version); print('Tk:', tkinter.TkVersion)"

# Sistema operacional
python -c "import platform; print(platform.platform())"

# Versão do Codis
python -c "from src.constants import APP_VERSION; print(APP_VERSION)"

# Dependências instaladas
pip list | grep -E "Pillow|markdown|psutil|websockets|send2trash|charset|Pygments"

# Log com debug ativado (últimas 100 linhas)
CODIS_DEBUG=1 python run.py 2>&1 | tail -100

Cole essas informações no template de bug report: 🐛 Abrir bug report

Codis compilado: pip, venv, LSP e Git#

O executável compilado (PyInstaller) não inclui um interpretador Python para os subprocessos. O Codis procura um Python 3.12+ instalado (PATH, py -3 no Windows, pastas padrão) e o valida executando-o. Se o painel pip mostrar "Python não encontrado":

Instale o Python em python.org (marque Add to PATH), ou
defina CODIS_PYTHON com o caminho do python/python.exe e reinicie.

Garantias contra cascata de processos: o Codis nunca executa a si mesmo como Python; quando chamado como Codis -m modulo ou Codis -c codigo ele se comporta como interpretador (módulos embutidos apenas) em vez de abrir a interface, e recusa iniciar com profundidade de spawn acima de 4 (CODIS_SPAWN_DEPTH). O ambiente dos subprocessos é limpo das variáveis do bundle (LD_LIBRARY_PATH, TCL_LIBRARY, TK_LIBRARY).