Módulo 3.4 — Troubleshooting de setup

⏱️ Diagnóstico em 5 minutos — rode SEMPRE primeiro

hermes doctor

Roda 30+ checks: Python, deps, provider, canais, disco, permissões. 90% dos erros aparecem aqui.

HERMES_DEBUG=1 hermes ...

Rerode o comando que falha com debug ligado. Stack trace completo + payload de cada chamada externa.

tail -f ~/.hermes/logs/hermes.log

Acompanhe em outro terminal enquanto reproduz. Mensagens nível ERROR e WARN dizem onde olhar.

🐍 Python e dependências

Erros #1 a #4. Quase sempre versão errada de Python ou conflito de pacote global.

#1 · Python 3.10 ou inferior

ERROR: hermes-agent requires Python >=3.11.0,
but you have 3.10.12. Aborting.

Causa: distros antigas (Ubuntu 22.04 vem com 3.10) não atendem.

Fix:

sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt install python3.12 python3.12-venv
python3.12 -m venv ~/.hermes/venv
source ~/.hermes/venv/bin/activate
pip install hermes-agent

#2 · pip externally-managed

error: externally-managed-environment
× This environment is externally managed
╰─> To install Python packages system-wide, try apt...

Causa: Debian 12 / Ubuntu 24.04 bloqueiam pip global (PEP 668).

Fix: use venv ou pipx, NUNCA --break-system-packages.

sudo apt install pipx
pipx install hermes-agent
pipx ensurepath

#3 · Virtualenv ativado errado

bash: hermes: command not found

Causa: instalou no venv, abriu novo terminal sem reativar.

Fix:

# diagnóstico
which hermes && pip show hermes-agent

# fix permanente — adicione ao ~/.bashrc
echo 'source ~/.hermes/venv/bin/activate' >> ~/.bashrc

#4 · Conflito tiktoken / numpy

ImportError: numpy.core.multiarray failed to import
(tiktoken installed against numpy 1.x, runtime has 2.x)

Causa: wheel pré-compilada de tiktoken contra numpy antigo.

Fix:

pip install --upgrade --force-reinstall \
  tiktoken numpy
hermes doctor

🔌 Conectividade — firewall, DNS, proxy

Erros #5 a #7. Comuns em VPN corporativa, Wi-Fi de hotel, container Docker mal configurado.

#5 · Timeout em openrouter.ai

httpx.ConnectTimeout: timed out
  while connecting to https://openrouter.ai/api/v1/chat/completions

Causa: firewall corporativo bloqueia ou proxy não está sendo respeitado.

Diagnóstico:

curl -v https://openrouter.ai/api/v1/models
# se falhar:
export HTTPS_PROXY=http://proxy.empresa:3128
export HTTP_PROXY=http://proxy.empresa:3128
hermes config set network.trust_env true

#6 · DNS quebrado (Termux/WSL)

socket.gaierror: [Errno -3] Temporary failure
  in name resolution

Causa: /etc/resolv.conf vazio ou apontando pra DNS interno.

Fix:

cat /etc/resolv.conf
echo "nameserver 1.1.1.1" | sudo tee /etc/resolv.conf
# WSL: desabilita auto-gen
sudo tee /etc/wsl.conf <<'EOF'
[network]
generateResolvConf = false
EOF

#7 · SSL CERT_VERIFY_FAILED

ssl.SSLCertVerificationError: [SSL: CERTIFICATE_VERIFY_FAILED]
certificate verify failed: unable to get local issuer certificate

Causa: CA bundle desatualizado ou proxy MITM (Zscaler, Netskope).

Fix:

pip install --upgrade certifi
# com MITM corporativo:
export REQUESTS_CA_BUNDLE=/etc/ssl/certs/empresa-root.pem
export SSL_CERT_FILE=/etc/ssl/certs/empresa-root.pem

⚠️ Nunca faça

NUNCA passe verify=False ou HERMES_INSECURE_SSL=1 em produção pra "resolver" SSL. Isso aceita qualquer certificado — qualquer atacante MITM lê suas API keys em texto puro. Arrume o CA bundle.

🔐 Autenticação — keys e tokens inválidos

Erros #8 a #10. Tipicamente copy/paste com espaço, token vencido, ou scope errado.

#8 · OpenRouter 401 Unauthorized

openrouter.AuthenticationError: 401 Unauthorized
  {"error": {"message": "No auth credentials found",
    "code": 401}}

Causa: key com espaço extra, key revogada, ou env var não exportada.

Fix:

# verifica o que está carregado
hermes config get provider.openrouter.api_key
# (mostra sk-or-v1-***** se ok, vazio se não)

# testa direto
curl -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  https://openrouter.ai/api/v1/auth/key

#9 · Telegram token inválido

telegram.error.InvalidToken: Invalid token
  {"ok":false,"error_code":401,"description":"Unauthorized"}

Causa: token sem os :, revogado no BotFather, ou de outro bot.

Fix:

# formato correto: 10dígitos:35caracteres
# teste direto:
curl https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/getMe
# se 401 → @BotFather → /token → escolhe bot → /revoke + /token

#10 · Discord 403 / intent faltando

discord.errors.PrivilegedIntentsRequired:
  Shard ID None is requesting privileged intents
  that have not been explicitly enabled in the
  developer portal.

Causa: esqueceu de ativar MESSAGE CONTENT INTENT.

Fix: discord.com/developers/applications → seu bot → Bot → toggle "MESSAGE CONTENT INTENT" → Save → reinicie hermes channel restart discord.

#11 · Slack invalid_auth

slack_sdk.errors.SlackApiError:
  The request to the Slack API failed.
  {'ok': False, 'error': 'invalid_auth'}

Causa: trocou xoxb- (bot) por xapp- (app), ou app não foi reinstalada após mudar scopes.

Fix: api.slack.com/apps → Install App → Reinstall to Workspace; reconfirme SLACK_BOT_TOKEN=xoxb-... e SLACK_APP_TOKEN=xapp-....

💾 Sistema de arquivos — permissões, disco, paths

Erros #12 a #14. Quase sempre ~/.hermes/ com dono errado ou disco cheio sem você notar.

#12 · Permission denied em ~/.hermes

PermissionError: [Errno 13] Permission denied:
  '/home/nei/.hermes/config.toml'

Causa: rodou sudo hermes setup uma vez, agora arquivos pertencem a root.

Fix:

sudo chown -R $USER:$USER ~/.hermes
chmod 700 ~/.hermes
chmod 600 ~/.hermes/config.toml ~/.hermes/.env

#13 · Disco cheio (no space left)

OSError: [Errno 28] No space left on device
  while writing ~/.hermes/memory/alice.db

Causa: logs e embeddings crescendo sem limite.

Diagnóstico:

df -h ~
du -sh ~/.hermes/* | sort -h
hermes maintenance compact --vacuum
hermes maintenance prune-logs --older-than 30d

#14 · Path com espaço (Windows)

FileNotFoundError: 'C:\\Users\\Nei
Maldaner\\.hermes\\config.toml'
The system cannot find the path specified.

Causa: usuário Windows com espaço no nome quebra parsers Python antigos.

Fix: mude HERMES_HOME pra path sem espaço.

setx HERMES_HOME "C:\hermes"
# reabra PowerShell
hermes setup

🤖 Modelo / provider — não existe, rate limit, fallback

Erros #15 a #17. Modelos do OpenRouter mudam de nome e free tiers têm rate-limit agressivo.

#15 · Model not found

openrouter.NotFoundError: 404
  {"error":{"message":"No allowed providers
  are available for the selected model",
  "code":404}}

Causa: nome do modelo errado (ex: claude-sonnet-4 ao invés de anthropic/claude-sonnet-4.5) ou modelo descontinuado.

Fix:

hermes models list --provider openrouter | grep claude
# ou direto:
curl https://openrouter.ai/api/v1/models | jq '.data[].id' | grep -i claude

#16 · 429 Rate limit

openrouter.RateLimitError: 429 Too Many Requests
  {"error":{"message":"Rate limit exceeded:
   free-models-per-day","code":429}}

Causa: modelos :free têm limite de 20 req/min e 200/dia.

Fix: configure fallback chain pra cair em modelo pago automaticamente.

hermes config set model.fallback '[
  "meta-llama/llama-3.3-70b-instruct:free",
  "anthropic/claude-haiku-4.5",
  "openai/gpt-4o-mini"
]'

#17 · Context length exceeded

openrouter.BadRequestError: 400
  This model's maximum context length is
  128000 tokens. However, you requested 142318 tokens.

Causa: histórico cresceu demais ou anexou arquivos grandes.

Fix:

# compressão automática
hermes config set memory.auto_compress true
hermes config set memory.compress_at_pct 70

# zera contexto da sessão atual
hermes chat /clear

📊 Sintoma → modelo provável

Resposta vazia + sem erro: modelo recusou silenciosamente (content filter). Tente outro.
Respostas curtíssimas: max_tokens muito baixo. Default no Hermes: 4096.
Respostas em inglês quando você fala PT: system prompt do modelo dominou. Force response_language: "pt-BR".
Custo subiu 10x sem motivo: fallback caiu num modelo caro. Veja hermes usage --by-model.

🌐 Runtime — porta, processo, crash

Erros #18 a #20. Aparecem quando você roda como serviço (systemd, supervisor, Docker).

#18 · Porta 7777 ocupada

OSError: [Errno 98] Address already in use
  Could not bind to ('0.0.0.0', 7777)

Causa: outro Hermes (ou processo) já está na porta.

Diagnóstico:

ss -tlnp | grep 7777
# ou no macOS:
lsof -i :7777

# mata o velho:
hermes stop --force
# ou:
kill $(lsof -ti:7777)

# muda a porta:
hermes config set server.port 7778

#19 · Processo zumbi (PID inválido)

hermes status
  STATE: running (PID 14523)
  but: ps -p 14523 → no such process
  → state file ~/.hermes/hermes.pid is stale

Causa: processo morreu sem limpar PID file (kill -9, crash, oom).

Fix:

hermes stop --clean-state
rm -f ~/.hermes/hermes.pid ~/.hermes/hermes.sock
hermes start

#20 · Crash silencioso (systemd)

systemctl status hermes
  ● hermes.service - Hermes Agent
     Active: failed (Result: exit-code) since ...
     Process: 14523 ExecStart=/usr/local/bin/hermes start
              (code=exited, status=137)

Causa: exit 137 = killed por OOM. Logs do app não capturam.

Diagnóstico real:

journalctl -u hermes -n 100 --no-pager
dmesg | grep -i 'killed process'
# fix: limita memória do hermes
hermes config set runtime.max_memory_mb 2048
sudo systemctl edit hermes
# adicione:
#   [Service]
#   MemoryMax=3G
sudo systemctl daemon-reload
sudo systemctl restart hermes

Bônus · hermes doctor --deep

Quando NADA acima funciona:

HERMES_DEBUG=1 hermes doctor --deep \
  --include-network \
  --include-permissions \
  --export ~/hermes-diag.json

# Envie esse JSON pro Discord da Nous Research:
# https://discord.gg/NousResearch
# Canal #hermes-support

⚠️ NUNCA "limpa tudo e reinstala"

A reação reflexa de apagar ~/.hermes/ destrói memórias, prompts customizados e configs de TODOS os tenants. Antes de qualquer "rm -rf", rode hermes backup create --full. Restauração leva 30 segundos; perda de 6 meses de memória, irreversível.

💡 Dica — sempre HERMES_DEBUG=1 primeiro

Antes de abrir issue ou perguntar no Discord, rerode com HERMES_DEBUG=1. 80% das vezes a mensagem extra resolve sozinho. Quando precisa pedir ajuda, cole APENAS o stack trace + 10 linhas antes — ninguém lê paste de 500 linhas.

✅ Resumo do Módulo

✓

Diagnóstico em 5 min

hermes doctor → HERMES_DEBUG=1 → tail -f logs

✓

Python & deps

3.11+, pipx ou venv, nunca --break-system-packages

✓

Conectividade

proxy via HTTPS_PROXY, DNS 1.1.1.1, REQUESTS_CA_BUNDLE em MITM

✓

Auth dos canais

curl /getMe pra Telegram, MESSAGE CONTENT intent pra Discord

✓

Filesystem & disco

chown sem sudo, maintenance prune-logs regular

✓

Runtime estável

ss -tlnp, journalctl, limite de memória no systemd

Próxima trilha:

T4 — 🛠️ Manutenção: updates, logs, debugging contínuo e como manter sua instalação saudável a longo prazo.

← Voltar para Trilha Próximo →