---
url: https://developers.zarv.com/edge-agent/troubleshooting.md
---
# Solução de problemas

Guia rápido para diagnosticar uma instalação do Zarv Agent. Salvo indicação
em contrário, os comandos abaixo são para a instalação **nativa** (systemd).

## Logs e estado

```sh
# Estado do serviço
systemctl status zarv-agent

# Logs (siga em tempo real com -f)
journalctl -u zarv-agent -f

# Logs do boot atual
journalctl -u zarv-agent -b
```

Os logs são estruturados (JSON por padrão; veja `EDGE_AGENT_LOG_FORMAT` em
[Configuração](/edge-agent/configuration)).

No Docker:

```sh
docker logs -f zarv-agent
```

## Endpoints de saúde locais

A interface local expõe endpoints úteis para diagnóstico (porta `8088`):

| Endpoint          | O que retorna                                                                                                                                   |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `GET /api/health` | Checagens de subsistemas (banco, disco, memória, conectividade, captores de câmera, goroutines). HTTP 200 saudável/degradado, 503 não-saudável. |
| `GET /api/status` | Estado do agente: `registered`, `online`, `paused`, `revoked`, e status de upload/inferência/telemetria/atualização.                            |
| `GET /healthz`    | Liveness simples (sempre 200 se o processo está de pé).                                                                                         |
| `GET /readyz`     | Readiness (503 se não registrado ou sem sincronizar há muito tempo).                                                                            |

```sh
curl -fsS http://127.0.0.1:8088/api/health | jq .
curl -fsS http://127.0.0.1:8088/api/status | jq .
```

## O serviço não inicia

```sh
systemctl status zarv-agent
journalctl -u zarv-agent -b | tail -50
```

* Confirme que o binário existe: `/usr/local/bin/zarv-agent`.
* Confirme o conffile: `/etc/default/zarv-agent`.
* O serviço roda como o usuário `zarv-agent`; o diretório de dados
  `/var/lib/zarv-agent` deve pertencer a ele. Reinstalar o pacote corrige a
  posse automaticamente.

## A interface local não abre

* O agente escuta em `0.0.0.0:8088` por padrão (`EDGE_AGENT_HTTP_LISTEN`).
* Verifique a porta:

```sh
curl -fsS -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8088/   # → 200
ss -lntp | grep 8088
```

* Se outra aplicação usa a 8088, altere `EDGE_AGENT_HTTP_LISTEN` em
  `/etc/default/zarv-agent` e reinicie.

## O agente fica "offline"

O agente precisa de **saída HTTPS (porta 443) para `collector.zarv.com`**.

```sh
# Resolução de DNS + conectividade
getent hosts collector.zarv.com
curl -fsS -o /dev/null -w "%{http_code}\n" https://collector.zarv.com
```

* Libere `collector.zarv.com:443` no firewall/proxy de saída.
* O estado `online` é determinado por sondagem periódica de conectividade; após
  liberar a rede, o agente volta a `online` automaticamente.

## "Registro necessário" / revogado

Se a interface mostrar aviso de registro ou `/api/status` retornar
`"revoked": true`, o acesso foi cancelado na Zarv. Gere uma nova chave de
enrollment e re-registre — veja
[Registro › Re-registro](/edge-agent/enrollment#re-registro-apos-revogacao).

## Câmeras não aparecem / sem eventos

* As câmeras são configuradas **centralmente pela Zarv**; confirme que o
  edge-server tem câmeras atribuídas no painel.
* O agente precisa de rota até as câmeras (RTSP/ONVIF) dentro do perímetro.
* A interface local mostra a saúde por câmera (conectividade + qualidade de
  imagem) na visão de câmeras.

## Disco cheio

O agente monitora a partição de dados. Acima de ~95% de uso ele entra em modo
**degradado**: recusa novas gravações de blobs e reduz a retenção de eventos
pendentes; recupera abaixo de ~80%.

```sh
df -h /var/lib/zarv-agent
```

Libere espaço na partição de `/var/lib/zarv-agent` (ou aponte
`EDGE_AGENT_DATA_DIR` para um volume maior e reinicie).

## A atualização não aplica

* Veja o estado em `/api/status` (campo de atualização) ou no painel da Zarv.
* Se o estado for `waiting_window`, há uma [janela de
  manutenção](/edge-agent/updates) configurada e o agente aplicará a atualização
  quando a janela abrir.
* `error` traz a última falha; confira também a conectividade de saída.