What causes "Unable to load image from file : ' ' for plugin: " in pentaho/pentaho-kettle?

Inspect the cause chain (getCause) to find the underlying IO/decode exception

pentaho/pentaho-kettle · error · KettleException

Unable to load image from file

Error message

Unable to load image from file : '<imageFile>' for plugin: <plugin>

What it means

Wrapper KettleException thrown when any Throwable escapes getUniversalImageIcon while loading a plugin image (e.g. IOException decoding the image, class loading failure). It reports the image file and plugin but hides the underlying cause as the cause chain.

Solutions

Inspect the cause chain (getCause) to find the underlying IO/decode exception
Replace the corrupt or unsupported icon file with a valid PNG/SVG
Re-checkout or re-download plugin resources and verify checksums
Convert the icon to a format supported by the Kettle Swing image loader

Example fix

// before: zero-byte icons/step.png
// after: replace with a valid PNG
file icons/step.png -> 128x128 valid PNG, rebuild plugin jar

Defensive patterns

Strategy: try-catch

Validate before calling

// verify readability before load
java.io.File f = new java.io.File(plugin.getImageFile());
if (f.exists() && f.length() == 0) throw new IllegalStateException("Corrupt empty image: " + f);

Try / catch

try { return getUniversalImageIcon(plugin); }
catch (KettleException e) {
  log.logError("Image decode failed: " + plugin.getImageFile() + ", cause=" + e.getCause(), e);
  return fallbackImage;
}

Prevention

Always inspect getCause() — this error wraps the real exception
Validate icons open in a standard image viewer before packaging
Use git lfs / binary-safe transfer to avoid corruption

When it happens

Trigger: The image file was found but reading/decoding it threw: corrupt PNG/GIF/SVG, truncated file, unsupported format, or an IO error while reading the stream.

Common situations: Icons corrupted during transfer/checkout (line-ending conversion), zero-byte files from failed downloads, image formats not supported by SwingGraphicsUtilities.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

AI-assisted analysis of pentaho/pentaho-kettle@f3058517a1 (2026-09-13). Data as JSON: /api/errors/712b0066744f855d. Report an issue: GitHub.

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/core/gui/SwingGUIResource.java:193

            BufferedImage bitmap = ImageIO.read( inputStream );

            WaitingImageObserver wia = new WaitingImageObserver( bitmap );
            wia.waitImageLoaded();

            image = new SwingUniversalImageBitmap( bitmap );
          } finally {
            IOUtils.closeQuietly( inputStream );
          }
        }
      }

      if ( image == null ) {
        throw new KettleException( "Unable to find file: " + plugin.getImageFile() + " for plugin: " + plugin );
      }

      return image;
    } catch ( Throwable e ) {
      throw new KettleException( "Unable to load image from file : '"
        + plugin.getImageFile() + "' for plugin: " + plugin, e );
    }
  }

  public Map<String, SwingUniversalImage> getEntryImages() {
    return entryImages;
  }

  public Map<String, SwingUniversalImage> getStepImages() {
    return stepImages;
  }
}

View on GitHub (pinned to f3058517a1)