# Erros de runtime

> Exceções e falhas em execução — MainWindow, FrameBuffer, thread de fundo, UI no construtor.

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

# Erros de runtime

Formato: **sintoma → causa → correção**.

## `MainWindow` não carrega (erro de reflexão / "class not found")
**Causa:** a classe raiz não estende `Window` **ou** não tem construtor público sem-args.
**Correção:**
```java
public class MainWindow extends Window {
   public MainWindow() { }   // construtor sem-args (obrigatório para a reflexão)
   @Override public void onShow() throws Exception { super.onShow(); /* … */ }
}
```
([Anatomia de projeto](/docs/get-started/project-structure))

## "FrameBuffer not disposed! Must call Image.apply after Image.getGraphics!"
**Causa:** você desenhou **off-screen** numa `Image` e não confirmou (commit).
**Correção:** desenhe com `Image.getPaint()` e finalize com `paint.finish()` (ou `image.applyChanges()`),
tudo dentro de `Main.runOnPaintThreadAndWait(...)`:
```java
Main.runOnPaintThreadAndWait(() -> {
   Paint p = img.getPaint();
   // … desenhar em p …
   p.finish();               // confirma (equivalente a img.applyChanges())
});
```
> ⚠️ Divergência: a **mensagem de erro** cita `getGraphics()`/`apply()` (nomes antigos); os métodos
> reais são **`getPaint()`** e **`finish()`/`applyChanges()`**. (Cap. 18)

## Componente alterado numa thread de fundo trava/corrompe a UI
**Causa:** toda manipulação de UI é na **paint thread**.
**Correção:** volte com `Component.onUI(r)` / `Main.runOnPaintThread(r)`.
```java
new Thread(() -> { var v = calc(); Component.onUI(() -> label.setText(v)); }).start();
```
([A paint thread](/docs/concepts/the-paint-thread))

## UI montada no construtor aparece vazia / com bounds errados
**Causa:** no construtor, a tela/bounds ainda não estão prontos.
**Correção:** monte em `onShow()` com `super.onShow()`. (Cap. 7)

## Exceção em `onAction` "some" sem travar a app
**Causa:** handlers são capturados por `Debug.handle` e **engolidos** — não borbulham.
**Correção:** não conte com propagação; logue (`Debug.log`/`Debug.handle`) e cheque o `DebugConsole.txt`.
([Erros e logging](/docs/best-practices/tratamento-de-erros-e-logging))

## Veja também
- [Problemas de renderização](/docs/troubleshooting/render) · [Build e Gradle](/docs/troubleshooting/build-gradle)