Skip to content

troubleshooting

Jump to bottom
github-actions[bot] edited this page Nov 13, 2026 · 1 revision

🛠️ 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

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:

  1. 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

  2. Tkinter não instalado - veja a seção Erro: "No module named tkinter".

  3. Configuração corrompida - veja Configurações corrompidas / reset.

  4. 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:

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

  2. 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

  3. 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

  4. 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:

  1. Abra Configurações → Performance
  2. Reduza large_file_threshold_kb (padrão: 500)
  3. Desative minimap_enabled para arquivos grandes
  4. 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:

  1. Erro de sintaxe no plugin - o plugin tem um bug que impede o carregamento. Verifique o log.
  2. Dependência faltando - o plugin requer um pacote não instalado. Veja a documentação do plugin.
  3. 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":

  1. Instale o Python em python.org (marque Add to PATH), ou
  2. 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).

📖 Início

Começando

Editando

Assistente e conectividade

Ferramentas e extras

Para quem desenvolve

Projeto

Clone this wiki locally