Troubleshooting

Guia de resolução de problemas do moclojer. Soluções para erros comuns, debugging tips e como obter ajuda quando algo não funciona.

Este guia ajuda você a resolver problemas comuns ao usar moclojer. Os problemas estão organizados por categoria para facilitar a busca.

🚀 Início Rápido

Antes de começar o troubleshooting:

✅ Verifique a versão do moclojer
```
moclojer --version
```

✅ Teste com configuração mínima

- endpoint:
    path: /test
    response:
      body: "ok"

✅ Verifique os logs do servidor

moclojer --config mocks.yml 2>&1 | tee moclojer.log

📁 Problemas de Configuração

"Config file not found"

Sintoma:

Error: Config file not found: moclojer.yml

Causas e Soluções:

Arquivo não existe no caminho especificado

# Verificar se arquivo existe
ls -la moclojer.yml

# Se não existe, criar
cat > moclojer.yml <<EOF
- endpoint:
    path: /hello
    response:
      body: "Hello!"
EOF

Caminho relativo incorreto

# ❌ Errado (busca no diretório errado)
cd /home/user
moclojer --config project/mocks.yml

# ✅ Correto (use caminho absoluto ou navegue até o diretório)
cd /home/user/project
moclojer --config mocks.yml

# Ou use caminho absoluto
moclojer --config /home/user/project/mocks.yml

Arquivo na localização XDG padrão

# Moclojer busca em ~/.config/moclojer.yml por padrão
# Verificar
ls -la ~/.config/moclojer.yml

# Ou definir XDG_CONFIG_HOME
export XDG_CONFIG_HOME=/my/custom/path
moclojer  # Busca em /my/custom/path/moclojer.yml

"YAML parse error"

Sintoma:

Error: YAML parse error at line 10: mapping values are not allowed here

Causas e Soluções:

Indentação incorreta (espaços vs tabs)

# ❌ Errado (mistura tabs e espaços)
- endpoint:
 method: GET    # Tab aqui!
    path: /users   # Espaços aqui!

# ✅ Correto (sempre 2 espaços)
- endpoint:
    method: GET
    path: /users

Solução: Configure seu editor para usar "soft tabs" (espaços)

VS Code: "editor.insertSpaces": true, "editor.tabSize": 2
Vim: set expandtab shiftwidth=2

Dois-pontos em string sem aspas

# ❌ Errado
body: http://example.com

# ✅ Correto (use aspas para URLs)
body: "http://example.com"

# ✅ Ou use bloco multi-linha
body: >
  http://example.com

JSON inline mal formatado

# ❌ Errado
body: {"key": "value"}

# ✅ Correto (use > para JSON)
body: >
  {"key": "value"}

# ✅ Ou multi-linha
body: >
  {
    "key": "value"
  }

Aspas não fechadas

# ❌ Errado
body: "Hello

# ✅ Correto
body: "Hello"

Ferramentas de validação:

# Online
# http://www.yamllint.com/

# CLI (se yamllint estiver instalado)
yamllint moclojer.yml

# Ver linha específica do erro
sed -n '10p' moclojer.yml

"Invalid JSON in response body"

Sintoma: Response body não é JSON válido, mas você esperava JSON.

Soluções:

Use > para JSON multi-linha

# ❌ Pode quebrar
body: {
  "key": "value"
}

# ✅ Sempre funciona
body: >
  {
    "key": "value"
  }

Escape de aspas em templates

# ❌ Quebra o JSON
body: >
  {
    "message": "Hello "{{path-params.name}}"!"
  }

# ✅ Sem aspas extras ao redor do template
body: >
  {
    "message": "Hello {{path-params.name}}!"
  }

Números sem aspas, strings com aspas

# Correto
body: >
  {
    "id": {{path-params.id}},
    "name": "{{path-params.name}}"
  }

🌐 Problemas de Servidor

"Address already in use"

Sintoma:

Error: Address already in use: 0.0.0.0:8000

Causa: Outra aplicação está usando a porta 8000.

Soluções:

Descobrir qual processo está usando a porta

# macOS/Linux
lsof -i :8000

# Linux alternativo
netstat -tlnp | grep 8000

# Windows
netstat -ano | findstr :8000

Matar o processo

# macOS/Linux
kill -9 <PID>

# Ou killall
killall -9 moclojer

Usar porta diferente

moclojer --port 8001

# Ou variável de ambiente
export MOCLOJER_PORT=8001
moclojer

"Server started but requests timeout"

Sintoma: Servidor inicia, mas requests nunca respondem.

Causas e Soluções:

Firewall bloqueando conexões

# macOS: permitir conexões entrantes
# System Preferences > Security > Firewall

# Linux: verificar iptables
sudo iptables -L

# Temporariamente desabilitar firewall para testar
sudo ufw disable  # Ubuntu

Binding em IP errado

# Se bindou em 127.0.0.1, apenas localhost funciona
moclojer --host 127.0.0.1  # Apenas local

# Para aceitar de qualquer interface
moclojer --host 0.0.0.0  # Todas as interfaces

Proxy ou VPN interferindo

# Desabilitar proxy temporariamente
unset HTTP_PROXY HTTPS_PROXY

# Ou configurar exceções
export NO_PROXY=localhost,127.0.0.1

🔍 Problemas de Matching

"404 Not Found" quando deveria fazer match

Sintoma: Você faz um request mas recebe 404, mesmo tendo um endpoint configurado.

Debugging:

Verificar método HTTP

# Se configurou GET
- endpoint:
    method: GET
    path: /users

# POST não vai funcionar!
curl -X POST http://localhost:8000/users  # 404

# Solução: usar GET
curl http://localhost:8000/users  # 200

Verificar path exato

# Configurado
path: /api/users

# ❌ Não funciona
curl http://localhost:8000/users  # 404

# ✅ Funciona
curl http://localhost:8000/api/users  # 200

Case sensitivity

# Configurado
path: /Users

# ❌ Cuidado com maiúsculas!
curl http://localhost:8000/users  # 404

# ✅ Deve ser exato
curl http://localhost:8000/Users  # 200

Tipo de path parameter incorreto

# Configurado com tipo int
path: /users/:id|int

# ❌ String não faz match
curl http://localhost:8000/users/abc  # 404

# ✅ Número faz match
curl http://localhost:8000/users/123  # 200

Ordem de precedência

# ❌ Ordem errada!
- endpoint:
    path: /users/:id      # Match genérico ANTES

- endpoint:
    path: /users/me       # Específico DEPOIS (nunca usado!)

# ✅ Ordem correta
- endpoint:
    path: /users/me       # Específico PRIMEIRO

- endpoint:
    path: /users/:id      # Genérico DEPOIS

Solução geral: Adicione logging temporário

- endpoint:
    path: /:any
    method: GET
    response:
      status: 200
      body: >
        {
          "debug": "Caught request to: /:any",
          "path": "{{path-params.any}}"
        }

Templates não são substituídos

Sintoma: Response contém {{path-params.id}} literal ao invés do valor.

Causas e Soluções:

Nome do parâmetro não corresponde

# ❌ Errado
path: /users/:userId
body: >
  {"id": "{{path-params.id}}"}  # id != userId!

# ✅ Correto
path: /users/:userId
body: >
  {"id": "{{path-params.userId}}"}

Sintaxe incorreta

# ❌ Errado
body: >
  {"id": "{{ path-params.id }}"}  # Espaços extras

# ✅ Correto
body: >
  {"id": "{{path-params.id}}"}  # Sem espaços

Query param não foi passado

path: /users
body: >
  {"role": "{{query-params.role}}"}

# Se não passar ?role=admin, fica vazio
curl http://localhost:8000/users
# {"role": ""}

# Solução: sempre passar o param
curl "http://localhost:8000/users?role=admin"
# {"role": "admin"}

🔄 Problemas de Hot-Reload

"Hot-reload não funciona"

Sintoma: Você modifica moclojer.yml mas mudanças não aparecem.

Causas e Soluções:

Não passou flag --watch

# ❌ Sem watch
moclojer --config mocks.yml

# ✅ Com watch
moclojer --config mocks.yml --watch

Usando binário nativo (GraalVM)

# Verificar
moclojer --version
# Se mencionar "native" ou "graalvm":

# Binário nativo NÃO suporta hot-reload
# Solução: usar JAR
java -jar moclojer.jar --config mocks.yml --watch

Editor salvando em arquivo temporário

# Alguns editores salvam em .tmp primeiro
# Moclojer pode não detectar

# Solução: forçar save direto
# VS Code: "files.watcherExclude" settings

Arquivo em filesystem remoto (NFS, etc)

# Hot-reload pode não funcionar em NFS/network drives
# Solução: copiar arquivo localmente

🐳 Problemas com Docker

"Container starts but can't connect"

Sintoma: Container do moclojer inicia mas você não consegue fazer requests.

Soluções:

Port mapping incorreto

# ❌ Errado (porta do host diferente)
docker run -p 3000:8000 moclojer
# Servidor escuta em 8000 dentro do container

# ✅ Correto
curl http://localhost:3000  # Porta do HOST

Config file não montado

# ❌ Config não está no container
docker run -p 8000:8000 moclojer --config /app/mocks.yml
# Error: file not found

# ✅ Mount do volume
docker run -p 8000:8000 \
  -v $(pwd)/mocks.yml:/app/mocks.yml \
  moclojer --config /app/mocks.yml

Servidor binding em 127.0.0.1 (dentro do container)

# ❌ Não acessível de fora do container
moclojer --host 127.0.0.1

# ✅ Bind em todas as interfaces
moclojer --host 0.0.0.0

🌍 Problemas de CORS

"CORS error in browser"

Sintoma:

Access to fetch at 'http://localhost:8000/api' from origin 'http://localhost:3000'
has been blocked by CORS policy

Solução:

Habilitar CORS globalmente

moclojer --enable-cors --config mocks.yml

Configurar CORS por endpoint

- endpoint:
    method: OPTIONS
    path: /:path
    response:
      status: 204
      headers:
        Access-Control-Allow-Origin: "*"
        Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
        Access-Control-Allow-Headers: Content-Type, Authorization

- endpoint:
    method: GET
    path: /api/users
    response:
      status: 200
      headers:
        Access-Control-Allow-Origin: "*"
      body: "[]"

CORS específico por origem

headers:
  Access-Control-Allow-Origin: "http://localhost:3000"
  Access-Control-Allow-Credentials: "true"

🔧 Debugging Avançado

Habilitar Logs Verbosos

# Capturar todos os logs
moclojer --config mocks.yml 2>&1 | tee moclojer.log

# Verificar requests recebidos
grep "Request" moclojer.log

# Verificar erros
grep -i error moclojer.log

Testar com curl -v (verbose)

curl -v http://localhost:8000/users

# Mostra:
# - Headers enviados
# - Headers recebidos
# - Response completo

Usar Proxy para Inspecionar

# Usar Charles Proxy, Fiddler ou mitmproxy
# para ver exatamente o que está sendo enviado/recebido

# mitmproxy exemplo
mitmproxy --port 8888

# Configurar client para usar proxy
curl --proxy http://localhost:8888 http://localhost:8000/users

Testar JSON com jq

# Validar se response é JSON válido
curl http://localhost:8000/users | jq .

# Se erro, JSON está malformado

🆘 Obtendo Ajuda

Antes de Pedir Ajuda

Prepare as seguintes informações:

Versão do moclojer
```
moclojer --version
```

Sistema operacional

uname -a  # Linux/macOS
ver       # Windows

Configuração mínima que reproduz o problema

# moclojer.yml (reduzido ao mínimo)
- endpoint:
    path: /test
    response:
      body: "ok"

Comando exato usado

moclojer --config moclojer.yml --port 8000

Erro completo (copie tudo!)
```
Error: ...
```
Request que você está fazendo
```
curl -v http://localhost:8000/test
```

Onde Pedir Ajuda

GitHub Discussions (perguntas gerais)
- https://github.com/moclojer/moclojer/discussions
GitHub Issues (bugs)
- https://github.com/moclojer/moclojer/issues
- Use template de bug report
FAQ (perguntas frequentes)
- FAQ

✅ Checklist de Troubleshooting

Quando algo não funciona, siga esta checklist:

📚 Veja Também

FAQ - Perguntas frequentes
CLI Reference - Todas as opções de linha de comando
Configuration Spec - Referência do YAML
YAML Format Guide - Sintaxe YAML

PreviousFAQ NextExamples Overview

Last updated 1 month ago

Was this helpful?

hashtag🚀 Início Rápido

hashtag📁 Problemas de Configuração

hashtag"Config file not found"

hashtag"YAML parse error"

hashtag"Invalid JSON in response body"

hashtag🌐 Problemas de Servidor

hashtag"Address already in use"

hashtag"Server started but requests timeout"

hashtag🔍 Problemas de Matching

hashtag"404 Not Found" quando deveria fazer match

hashtagTemplates não são substituídos

hashtag🔄 Problemas de Hot-Reload

hashtag"Hot-reload não funciona"

hashtag🐳 Problemas com Docker

hashtag"Container starts but can't connect"

hashtag🌍 Problemas de CORS

hashtag"CORS error in browser"

hashtag🔧 Debugging Avançado

hashtagHabilitar Logs Verbosos

hashtagTestar com curl -v (verbose)

hashtagUsar Proxy para Inspecionar

hashtagTestar JSON com jq

hashtag🆘 Obtendo Ajuda

hashtagAntes de Pedir Ajuda

hashtagOnde Pedir Ajuda

hashtag✅ Checklist de Troubleshooting

hashtag📚 Veja Também

🚀 Início Rápido

📁 Problemas de Configuração

"Config file not found"

"YAML parse error"

"Invalid JSON in response body"

🌐 Problemas de Servidor

"Address already in use"

"Server started but requests timeout"

🔍 Problemas de Matching

"404 Not Found" quando deveria fazer match

Templates não são substituídos

🔄 Problemas de Hot-Reload

"Hot-reload não funciona"

🐳 Problemas com Docker

"Container starts but can't connect"

🌍 Problemas de CORS

"CORS error in browser"

🔧 Debugging Avançado

Habilitar Logs Verbosos

Testar com curl -v (verbose)

Usar Proxy para Inspecionar

Testar JSON com jq

🆘 Obtendo Ajuda

Antes de Pedir Ajuda

Onde Pedir Ajuda

✅ Checklist de Troubleshooting

📚 Veja Também