# Errores de runtime

> Excepciones y fallos en ejecución — MainWindow, FrameBuffer, hilo de fondo, UI en el constructor.

Source: https://crossfly.dev/es/docs/troubleshooting/runtime — CrossFly documentation. Full docs as one file: https://crossfly.dev/llms-full.txt

# Errores de runtime

Formato: **síntoma → causa → corrección**.

## `MainWindow` no carga (error de reflexión / "class not found")
**Causa:** la clase raíz no extiende `Window` **o** no tiene constructor público sin argumentos.
**Corrección:**
```java
public class MainWindow extends Window {
   public MainWindow() { }   // constructor sin-args (obligatorio para la reflexión)
   @Override public void onShow() throws Exception { super.onShow(); /* … */ }
}
```
([Anatomía de proyecto](/docs/get-started/project-structure))

## "FrameBuffer not disposed! Must call Image.apply after Image.getGraphics!"
**Causa:** dibujaste **off-screen** en una `Image` y no confirmaste (commit).
**Corrección:** dibuja con `Image.getPaint()` y finaliza con `paint.finish()` (o `image.applyChanges()`),
todo dentro de `Main.runOnPaintThreadAndWait(...)`:
```java
Main.runOnPaintThreadAndWait(() -> {
   Paint p = img.getPaint();
   // … dibujar en p …
   p.finish();               // confirma (equivalente a img.applyChanges())
});
```
> ⚠️ Divergencia: el **mensaje de error** cita `getGraphics()`/`apply()` (nombres antiguos); los métodos
> reales son **`getPaint()`** y **`finish()`/`applyChanges()`**. (Cap. 18)

## Componente modificado en un hilo de fondo cuelga/corrompe la UI
**Causa:** toda manipulación de UI es en la **paint thread**.
**Corrección:** vuelve con `Component.onUI(r)` / `Main.runOnPaintThread(r)`.
```java
new Thread(() -> { var v = calc(); Component.onUI(() -> label.setText(v)); }).start();
```
([El paint thread](/docs/concepts/the-paint-thread))

## UI montada en el constructor aparece vacía / con bounds erróneos
**Causa:** en el constructor, la pantalla/bounds aún no están listos.
**Corrección:** monta en `onShow()` con `super.onShow()`. (Cap. 7)

## Excepción en `onAction` "desaparece" sin colgar la app
**Causa:** los handlers son capturados por `Debug.handle` y **tragados** — no se propagan.
**Corrección:** no cuentes con la propagación; loguea (`Debug.log`/`Debug.handle`) y revisa el `DebugConsole.txt`.
([Errores y logging](/docs/best-practices/tratamento-de-erros-e-logging))

## Ver también
- [Problemas de renderizado](/docs/troubleshooting/render) · [Build y Gradle](/docs/troubleshooting/build-gradle)