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