# Manejo de errores y logging

> Debug.handle como embudo de excepciones, reaccionar a errores específicos y mostrar fallos al usuario.

Source: https://crossfly.dev/es/docs/best-practices/tratamento-de-erros-e-logging — CrossFly documentation. Full docs as one file: https://crossfly.dev/llms-full.txt

# Manejo de errores y logging

El punto central es tener **un embudo único** de excepciones y separar "error que el usuario ve" de "error para el
log".

## El embudo: `Debug.handle(e)` y `Debug.log(...)`
```java
try {
   arriscado();
} catch (Exception e) {
   Debug.handle(e);        // loguea y trata de forma uniforme (embudo único)
}
Debug.log("estado:", valor);   // diagnóstico libre
```
Las animaciones y tasks del framework ya capturan `Throwable` vía `Debug.handle` internamente. **Por qué un
embudo:** una excepción no manejada **en la paint thread** derriba el frame — canalizarla evita el crash y da
un punto único para instrumentar.

## Reacciona a errores específicos (no engullas todo)
```java
try (SqliteDb db = SqliteDb.open("app.db")) {
   db.execute("INSERT INTO cliente(email) VALUES(?)", email);
} catch (SqliteException e) {
   if (e.code == Sqlite.CONSTRAINT) Hint.show("E-mail já cadastrado", 2000);   // 19
   else if (e.code == Sqlite.BUSY)  Hint.show("Banco ocupado, tente de novo", 2000);  // 5
   else Debug.handle(e);
}
```
`SqliteException.code` trae el código SQLite (`Sqlite.OK/BUSY/CONSTRAINT/LOCKED/...`). Lo mismo vale para
otros resultados tipados (ej.: `AuthResult.ERROR` de la biometría).

## Errores de callbacks de fondo → muéstralos en la UI con `onUI`
Los callbacks (red, GPS, BLE) se ejecutan **fuera** de la paint thread. Para avisar al usuario, hazles marshaling con `onUI`:
```java
new Thread(() -> {
   try { sincronizar(); }
   catch (Exception e) {
      Component.onUI(() -> Hint.show("Falha ao sincronizar", 2000));   // Hint = no bloqueante
      Debug.handle(e);
   }
}).start();
```
- **`Hint.show(...)`** para avisos no bloqueantes; **`Alert`** cuando exige una decisión del usuario.
- **Separa:** lo que el usuario necesita ver (`Hint`/`Alert`) vs. lo que va solo al log (`Debug.log`/`handle`).

## Flags de depuración
`Debug.traceKeyboard`, `Debug.showFPS`, `Debug.beepOnGC` ayudan a diagnosticar durante el desarrollo.

## Buenas prácticas
- **Un embudo** (`Debug.handle`) para lo que no es tratable específicamente.
- Trata códigos **específicos** (`CONSTRAINT`, `BUSY`) con un mensaje útil al usuario.
- Error de fondo → `onUI` + `Hint`/`Alert`; nunca toques la UI directo en el callback.

## Errores comunes
- `catch (Exception e) {}` vacío — engulle el problema.
- Mostrar el stack trace crudo al usuario (usa `Hint`/`Alert` con mensaje claro; el stack va al log).
- Tocar la UI desde un thread de fondo sin `onUI`.

## Ver también
- [Diálogos y modales](/docs/ui/navigation/dialogs-and-modals) · [Trabajo en background](/docs/data-and-services/background-work)