Using Panic's PlayDate Simulator Version 2.3.1 (165008) and Nova v11.8 (Build 573039) on a macOS Sonoma 14.2.1 (23C71), following the Inside PlayDate v2.3.1 SDK documentation, Section 6.16 Display for playdate.display.loadImage(), with this source:

1

playdate.display.loadImage("images/foobar")

I get this error message:

1
2
3
4

main.lua:31: loaded file properties don't match framebuffer's
stack traceback:
	[C]: in field 'loadImage'
	main.lua:31: in function <main.lua:24>

Panic recognizes it is a known bug introduced in May 2021 while trying to make font stoarage more efficient.

Solution

An ugly work around -- don't do this -- is to pad the image out to 416x240 pixels.

The correct workaround, and possibly long term fix, is:

1

playdate.graphics.image.new("images/foobar"):draw(0,0)

The images is loaded with image.new as a Lua object, and the draw method is invoked with the upper left screen coordinates.

Unfortunately, this isn't as fast as decompressing the image right into the framebuffer.