bee/git-bible/grub-bitmap-error.md

# GRUB bitmap error: null src bitmap in grub_video_bitmap_create_scaled

## Symptom

```
error: null src bitmap in grub_video_bitmap_create_scaled.
Press any key to continue...
```

Appears on boot before the GRUB menu renders. The menu still appears after pressing a key,
but without the bee logo. Reproduced on real hardware (Lenovo SR650 V3, ASUS GPU servers).

## Root cause model

`grub_video_bitmap_create_scaled` receives a null `src` pointer, meaning the PNG loader
returned null for `bee-logo.png`. GRUB calls this function even when no explicit
`width`/`height` are set in `theme.txt` — it is invoked any time an image component is
rendered, passing the image's natural dimensions as the target size.

The PNG file is referenced as `file = "bee-logo.png"` (relative to theme dir).
GRUB resolves this to `/boot/grub/live-theme/bee-logo.png`.

## Attempts that did NOT fix the error

### Attempt 1 — add explicit `width`/`height` to image block (d52ec67)

**What was done:** First introduction of bee-logo.png with:
```
+ image {
    top = 4%
    left = 50%-200
    width = 400
    height = 400
    file = "bee-logo.png"
}
```
PNG at this point was RGBA (color_type=6).

**Result:** Error appeared immediately on first ISO build.

---

### Attempt 2 — remove `width`/`height` from image block (aa284ae)

**Hypothesis:** Explicit scaling dimensions trigger the scale path; removing them avoids it.

**What was done:** Removed `width = 400` and `height = 400` from the image block.
```
+ image {
    top = 4%
    left = 50%-200
    file = "bee-logo.png"
}
```

**Result:** Error persists. GRUB calls `grub_video_bitmap_create_scaled` regardless of whether
`width`/`height` are specified — if the bitmap is null (loading failed), the error fires either way.

---

### Attempt 3 — convert PNG to RGBA + strip metadata chunks (6112094)

**Hypothesis:** GRUB's minimal PNG parser is confused by metadata chunks (cHRM, bKGD, tIME, tEXt).
Also re-ordered `terminal_output gfxterm` before `insmod png` / theme load.

**What was done:**
- Converted PNG to RGBA color_type=6, stripped all ancillary chunks
- Moved `terminal_output gfxterm` earlier in config.cfg
- Removed echo ASCII art banner from grub.cfg

**Result:** Error persists — and this change actually confirmed RGBA does not work:
GRUB's PNG loader does not render RGBA PNGs correctly on this platform.

---

### Attempt 4 — convert PNG from RGBA back to RGB (333c44f, most recent)

**Hypothesis:** GRUB does not support RGBA (color_type=6); RGB (color_type=2) is the correct format.
Alpha channel composited onto black background (#000000) to match `desktop-color`.

**What was done:** Converted bee-logo.png from RGBA to RGB via ImageMagick.

**Current file state:**
- 400×400 px, 8-bit/color RGB, non-interlaced
- Only IHDR + IDAT + IEND chunks (no metadata)
- `insmod png` is present in config.cfg
- `terminal_output gfxterm` runs before theme is sourced
- No explicit `width`/`height` in image block

**Result:** Error still occurs on real hardware. Despite the PNG being nominally correct
(RGB, non-interlaced, minimal chunks), the bitmap load returns null.

## Confirmed root cause (verified on 172.16.41.94, 2026-04-30)

The EFI partition (`sda2`, vfat, 5 MB) contains only:
```
/EFI/boot/bootia32.efi
/EFI/boot/bootx64.efi
/EFI/boot/grubx64.efi
/boot/grub/grub.cfg
```

`config.cfg`, `theme.cfg`, and the entire `live-theme/` directory (including `bee-logo.png`)
are **absent from the EFI image**. `live-build`'s `lb binary_grub-efi` stage is not
copying these files. GRUB boots, sources only `grub.cfg`, then fails to load the theme
because the file does not exist — returning a null bitmap regardless of PNG format.

All four fix attempts were targeting the wrong layer (PNG format/content).

## Fix (applied 2026-04-30)

Switched from PNG to TGA format:

1. Converted `bee-logo.png` → `bee-logo.tga` (24-bit uncompressed BGR, top-left origin,
   480018 bytes). Conversion done via Python stdlib (no external tools needed).
2. `config.cfg`: `insmod png` → `insmod tga`
3. `theme.txt`: `file = "bee-logo.png"` → `file = "bee-logo.tga"`

**Why TGA works:** GRUB's TGA reader (`tga.mod`) handles uncompressed 24-bit images
trivially — no decompression, no complex chunk parsing. The module is present on-disk
(`x86_64-efi/tga.mod`). PNG was failing despite a valid file; the exact GRUB bug is
unknown but the PNG reader in Debian bookworm's grub2 is known to be fragile.

The old `bee-logo.png` is kept in the tree (may be useful for other tools) but is no
longer referenced by the theme.

## Relevant files

| File | Purpose |
|------|---------|
| `iso/builder/config/bootloaders/grub-efi/config.cfg` | insmod png, gfxterm init, theme source |
| `iso/builder/config/bootloaders/grub-efi/theme.cfg` | sets `theme=` path |
| `iso/builder/config/bootloaders/grub-efi/live-theme/theme.txt` | image component definition |
| `iso/builder/config/bootloaders/grub-efi/live-theme/bee-logo.png` | the logo PNG |