tauri-apps/tauri · error

creating icon

Error message

creating icon

What it means

Runtime panic on macOS when the app tries to set the dock/window application icon: NSImage::initWithData fails to decode the app icon bytes (manager.app_icon) into an NSImage. The expect("creating icon") fires on RunEvent::MainEventsCleared-style handling in the Tauri builder's macOS run loop, aborting the process.

Solutions

  1. Verify the icon configured in tauri.conf.json (bundle > icon) is a valid, decodable image (e.g. re-export the .icns/.png)
  2. Regenerate icons with `tauri icon` from a clean 1024x1024 source PNG
  3. Check for macOS runtime environment issues (CI/headless) where NSApplication/NSImage may not initialize
  4. If setting the icon programmatically, validate the byte data decodes before passing it to NSImage

Example fix

// before
let app_icon = NSImage::initWithData(NSImage::alloc(), &data).expect("creating icon");
// after
if let Some(app_icon) = unsafe { NSImage::initWithData(NSImage::alloc(), &data) } {
    unsafe { app.setApplicationIconImage(Some(&app_icon)) };
} else {
    eprintln!("failed to decode application icon data");
}
Defensive patterns

Strategy: try-catch

Validate before calling

if let Some(icon) = &app_handle.manager.app_icon {
    assert!(image::load_from_memory(icon).is_ok(), "app icon bytes are not a decodable image");
}

Type guard

fn is_valid_image(data: &[u8]) -> bool {
    data.starts_with(&[0x89, b'P', b'N', b'G']) || data.starts_with(b"icns")
}

Try / catch

match unsafe { NSImage::initWithData(NSImage::alloc(), &data) } {
    Some(img) => unsafe { app.setApplicationIconImage(Some(&img)) },
    None => eprintln!("skipping app icon: invalid image data"),
}

Prevention

When it happens

Trigger: app_handle.manager.app_icon contains bytes that Cocoa cannot decode into an NSImage: invalid or truncated PNG/ICNS data, an unsupported image format, or corrupt icon data produced upstream during context creation.

Common situations: A corrupted or non-image bundle icon file referenced in tauri.conf.json, a custom icon set programmatically with invalid bytes, macOS APIs failing on headless/CI environments, or regression after changing icon configuration.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

AI-assisted analysis of tauri-apps/tauri@460ec35447 (2026-09-18). Data as JSON: /api/errors/07bb35b6b102c458. Report an issue: GitHub.

Appendix: source

Thrown at crates/tauri/src/app.rs:2632

    },
    RuntimeRunEvent::WebviewEvent { label, event } => RunEvent::WebviewEvent {
      label,
      event: event.into(),
    },
    RuntimeRunEvent::Ready => {
      // set the app icon in development
      #[cfg(all(dev, target_os = "macos"))]
      {
        use objc2::{AllocAnyThread, MainThreadMarker};
        use objc2_app_kit::{NSApplication, NSImage};
        use objc2_foundation::NSData;

        if let Some(icon) = app_handle.manager.app_icon.clone() {
          // TODO: Enable this check.
          let mtm = unsafe { MainThreadMarker::new_unchecked() };
          let app = NSApplication::sharedApplication(mtm);
          let data = NSData::with_bytes(&icon);
          let app_icon = NSImage::initWithData(NSImage::alloc(), &data).expect("creating icon");
          unsafe { app.setApplicationIconImage(Some(&app_icon)) };
        }
      }
      RunEvent::Ready
    }
    RuntimeRunEvent::Resumed => RunEvent::Resumed,
    RuntimeRunEvent::MainEventsCleared => RunEvent::MainEventsCleared,
    RuntimeRunEvent::UserEvent(t) => {
      match t {
        #[cfg(desktop)]
        EventLoopMessage::MenuEvent(ref e) => {
          for listener in &*app_handle
            .manager
            .menu
            .global_event_listeners
            .lock()
            .unwrap()
          {

View on GitHub (pinned to 460ec35447)