Custom icon apparently packaged, but not found when the app launches

[clayote]

Describe the bug

When I add an icon to my Briefcase app, it appears to be packaged correctly, but does not display on the running app, which logs WARNING: Can't find app icon; falling back to default icon.

How to reproduce the bug

1. Install Briefcase (I used a virtualenv on Linux Mint 22.3, Python 3.12.3)
2. Add an icon according to the "Customizing icons" tutorial
3. briefcase run --update-resources -r

Minimum example code

# This project was generated with 0.4.2 using template: https://github.com/beeware/briefcase-template @ v0.4.2
[tool.briefcase]
project_name = "Hello World"
bundle = "com.zacharyspector"
version = "0.0.1"
url = "https://zacharyspector.com/helloworld"
license = "BSD-3-Clause"
license-files = ["LICENSE"]
author = "Zachary Spector"
author_email = "public@zacharyspector.com"

[tool.briefcase.app.helloworld]
formal_name = "Hello World"
description = "My first application"
long_description = """More details about the app should go here.
"""
icon = "icons/helloworld"
sources = [
    "src/helloworld",
]
test_sources = [
    "tests",
]

requires = [
    "faker",
    "httpx",
]
test_requires = [
    "pytest",
]

I have omitted the remainder of pyproject.toml because it's the stock template with no changes at all. src/helloworld/__main__.py is similarly uninteresting, being the result of tutorial 8.

Screenshots

Environment details

• Operating system and version: Linux Mint 22.3
• Python version: 3.12.3
• Software versions:
  • Briefcase: 0.4.2
  • Toga: 0.5.4

Logs

(beeware-venv) sanotehu@zack-ThinkPad-X220:~/src/beeware-tutorial/helloworld$ briefcase run --update-resources -r

[helloworld] Updating application code...
Installing src/helloworld... done

[helloworld] Updating requirements...
Collecting faker
  Using cached faker-40.21.0-py3-none-any.whl.metadata (16 kB)
Collecting httpx
  Using cached httpx-0.28.1-py3-none-any.whl.metadata (7.1 kB)
Collecting toga-gtk~=0.5.0
  Using cached toga_gtk-0.5.4-py3-none-any.whl.metadata (3.6 kB)
Collecting pygobject<3.52.1
  Using cached pygobject-3.50.2-cp312-cp312-linux_x86_64.whl
Collecting packaging (from toga-gtk~=0.5.0)
  Using cached packaging-26.2-py3-none-any.whl.metadata (3.5 kB)
Collecting pycairo>=1.17.0 (from toga-gtk~=0.5.0)
  Using cached pycairo-1.29.0-cp312-cp312-linux_x86_64.whl
Collecting toga-core==0.5.4 (from toga-gtk~=0.5.0)
  Using cached toga_core-0.5.4-py3-none-any.whl.metadata (4.0 kB)
Collecting travertino==0.5.4 (from toga-core==0.5.4->toga-gtk~=0.5.0)
  Using cached travertino-0.5.4-py3-none-any.whl.metadata (3.0 kB)
Collecting anyio (from httpx)
  Using cached anyio-4.13.0-py3-none-any.whl.metadata (4.5 kB)
Collecting certifi (from httpx)
  Using cached certifi-2026.5.20-py3-none-any.whl.metadata (2.5 kB)
Collecting httpcore==1.* (from httpx)
  Using cached httpcore-1.0.9-py3-none-any.whl.metadata (21 kB)
Collecting idna (from httpx)
  Using cached idna-3.18-py3-none-any.whl.metadata (6.1 kB)
Collecting h11>=0.16 (from httpcore==1.*->httpx)
  Using cached h11-0.16.0-py3-none-any.whl.metadata (8.3 kB)
Collecting typing_extensions>=4.5 (from anyio->httpx)
  Using cached typing_extensions-4.15.0-py3-none-any.whl.metadata (3.3 kB)
Using cached toga_gtk-0.5.4-py3-none-any.whl (79 kB)
Using cached toga_core-0.5.4-py3-none-any.whl (167 kB)
Using cached travertino-0.5.4-py3-none-any.whl (27 kB)
Using cached faker-40.21.0-py3-none-any.whl (2.0 MB)
Using cached httpx-0.28.1-py3-none-any.whl (73 kB)
Using cached httpcore-1.0.9-py3-none-any.whl (78 kB)
Using cached h11-0.16.0-py3-none-any.whl (37 kB)
Using cached anyio-4.13.0-py3-none-any.whl (114 kB)
Using cached idna-3.18-py3-none-any.whl (65 kB)
Using cached typing_extensions-4.15.0-py3-none-any.whl (44 kB)
Using cached certifi-2026.5.20-py3-none-any.whl (134 kB)
Using cached packaging-26.2-py3-none-any.whl (100 kB)
Installing collected packages: typing_extensions, travertino, pycairo, packaging, idna, h11, faker, certifi, toga-core, pygobject, httpcore, anyio, toga-gtk, httpx

Successfully installed anyio-4.13.0 certifi-2026.5.20 faker-40.21.0 h11-0.16.0 httpcore-1.0.9 httpx-0.28.1 idna-3.18 packaging-26.2 pycairo-1.29.0 pygobject-3.50.2 toga-core-0.5.4 toga-gtk-0.5.4 travertino-0.5.4 typing_extensions-4.15.0
Installing app requirements... done

[helloworld] Updating application resources...
Installing icons/helloworld-16.png as 16px application icon... done
Installing icons/helloworld-32.png as 32px application icon... done
Installing icons/helloworld-64.png as 64px application icon... done
Installing icons/helloworld-128.png as 128px application icon... done
Installing icons/helloworld-256.png as 256px application icon... done
Installing icons/helloworld-512.png as 512px application icon... done

[helloworld] Removing unneeded app content...
Removing unneeded app bundle content... done

[helloworld] Application updated.

[helloworld] Building application...
Build bootstrap binary...
make: Entering directory '/home/sanotehu/src/beeware-tutorial/helloworld/build/helloworld/linuxmint/zena/bootstrap'
mkdir -p ../helloworld-0.0.1/usr/bin
cp helloworld ../helloworld-0.0.1/usr/bin
make: Leaving directory '/home/sanotehu/src/beeware-tutorial/helloworld/build/helloworld/linuxmint/zena/bootstrap'
Building bootstrap binary... done
Installing license... done
Installing changelog... done
Installing man page... done
Updating file permissions... done
Stripping binary... done

[helloworld] Built build/helloworld/linuxmint/zena/helloworld-0.0.1/usr/bin/helloworld

[helloworld] Starting app...
===========================================================================
WARNING: Can't find app icon; falling back to default icon

Additional context

I also tried briefcase create and it did the same thing.

[freakboy3742]

Thanks for the report. Those logs indicate that the icons are being installed, but can't be found at runtime; this suggests the issue is actually related to Toga, rather than Briefcase.

I'm wondering if this is actually a manifestation of beeware/toga#3565 - that the icon exists but it can't be loaded because GdkPixbuf doesn't have the plugin. See this comment for the diagnosis approach that worked out what was going on here.

To help diagnose this - in your generated app (in the build folder), there will be a toga_gtk/icons.py file. There should be multiple attempts to load that file; if you can print the value of "path", and log the exit condition for each invocation (i.e., print just before the function returns, or raises an exception), we can narrow down the sequence of events that has led to the icon failing to be found.