Java Aspose Imaging - Image loading failed for a .heic file

Aspose.Imaging Product Family
1

Hello, I have come across the imaging dependency of aspose which looks pretty good. Now i tried using it with the HEIC Adapter that is a openize wrapper. Sadly I did not manage to load the file.

I ran ffmpeg to check if the file is ok, this is the result:

ffmpeg -i IMG_3333.HEIC
ffmpeg version 7.1.1 Copyright (c) 2000-2025 the FFmpeg developers
  built with Apple clang version 17.0.0 (clang-1700.0.13.3)
  configuration: --prefix=/opt/homebrew/Cellar/ffmpeg/7.1.1_3 --enable-shared --enable-pthreads --enable-version3 --cc=clang --host-cflags= --host-ldflags='-Wl,-ld_classic' --enable-ffplay --enable-gnutls --enable-gpl --enable-libaom --enable-libaribb24 --enable-libbluray --enable-libdav1d --enable-libharfbuzz --enable-libjxl --enable-libmp3lame --enable-libopus --enable-librav1e --enable-librist --enable-librubberband --enable-libsnappy --enable-libsrt --enable-libssh --enable-libsvtav1 --enable-libtesseract --enable-libtheora --enable-libvidstab --enable-libvmaf --enable-libvorbis --enable-libvpx --enable-libwebp --enable-libx264 --enable-libx265 --enable-libxml2 --enable-libxvid --enable-lzma --enable-libfontconfig --enable-libfreetype --enable-frei0r --enable-libass --enable-libopencore-amrnb --enable-libopencore-amrwb --enable-libopenjpeg --enable-libspeex --enable-libsoxr --enable-libzmq --enable-libzimg --disable-libjack --disable-indev=jack --enable-videotoolbox --enable-audiotoolbox --enable-neon
  libavutil      59. 39.100 / 59. 39.100
  libavcodec     61. 19.101 / 61. 19.101
  libavformat    61.  7.100 / 61.  7.100
  libavdevice    61.  3.100 / 61.  3.100
  libavfilter    10.  4.100 / 10.  4.100
  libswscale      8.  3.100 /  8.  3.100
  libswresample   5.  3.100 /  5.  3.100
  libpostproc    58.  3.100 / 58.  3.100
[mov,mp4,m4a,3gp,3g2,mj2 @ 0x79d008000] Ignoring duplicate CLLI/COLL
    Last message repeated 29 times
Input #0, mov,mp4,m4a,3gp,3g2,mj2, from 'IMG_3333.HEIC':
  Metadata:
    major_brand     : heic
    minor_version   : 0
    compatible_brands: heicmif1
  Duration: N/A, start: 0.000000, bitrate: N/A
  Stream group #0:0[0x1f]: Tile Grid: hevc (Main Still Picture) (hvc1 / 0x31637668), yuvj420p(pc, smpte170m/unknown/unknown), 2180x2783 (default)
  Stream group #0:1[0x29]: Tile Grid: hevc (Rext) (hvc1 / 0x31637668), gray(pc), 1090x1392

These are the dependencies I included according to the github README:

<dependency>
      <groupId>com.aspose</groupId>
      <artifactId>aspose-imaging</artifactId>
      <version>25.4</version>
    </dependency>
    <dependency>
      <groupId>com.aspose</groupId>
      <artifactId>openize-heic</artifactId>
      <version>25.4</version>
    </dependency>
    <dependency>
      <groupId>com.aspose</groupId>
      <artifactId>aspose-imaging-heic-adapter</artifactId>
      <version>25.4</version>
    </dependency>

What I am trying to do is:
try (Image asposeImage = Image.load(inputStream)) {
ByteArrayOutputStream os = new ByteArrayOutputStream();
asposeImage.save(os, new PngOptions());
try (ByteArrayInputStream bis = new ByteArrayInputStream(os.toByteArray())) {
bufferedImage = ImageIO.read(bis);
}
}

There is also an error from openize:
Caused by: java.lang.IllegalArgumentException: 1668050025
at openize.isobmff.BoxType.codeToType(BoxType.java:380) ~[openize-heic-25.4.jar:25.4]

Thank you for your help in advance :slight_smile:

2

@dusto

Summary
Image.load() throws an IllegalArgumentException from openize.isobmff.BoxType.codeToType when trying to read the HEIC file. The file itself is valid (as shown by ffmpeg), so the problem is usually that the Aspose Imaging HEIC adapter is not registered or not discovered at runtime.

Why it happens

  • HEIC support in Aspose Imaging is supplied by the HEIC adapter (aspose-imaging-heic-adapter together with the openize-heic library).
  • The adapter must be registered once before any image‑loading operation. If the registration step is omitted, Aspose Imaging falls back to a generic ISO‑BMFF parser that cannot interpret HEIC‑specific boxes, leading to the IllegalArgumentException.
  • When the adapter JAR is packaged (e.g., inside a shaded/uber JAR), the service‑loader metadata may be lost, preventing automatic discovery of the codec.

What to do next

  1. Ensure the HEIC adapter JAR is on the runtime classpath (you already have aspose-imaging-heic-adapter and openize-heic). If you build a shaded JAR, verify that the file META-INF/services/com.aspose.imaging.fileformats.heic.HeicImage (or the corresponding service file) is retained.
  2. Register the adapter before any Image.load call. The adapter provides a static register() method (e.g., HeicImage.register();). Call it once at application start‑up:
import com.aspose.imaging.Image;
import com.aspose.imaging.fileformats.heic.HeicImage; // class that provides register()
import com.aspose.imaging.imageoptions.PngOptions;
import java.io.*;
import java.nio.file.*;

public class HeicDemo {
public static void main(String[] args) throws Exception {
// One‑time registration of the HEIC codec
HeicImage.register();

try (InputStream input = Files.newInputStream(Paths.get("IMG_3333.HEIC"));
Image img = Image.load(input)) {

ByteArrayOutputStream os = new ByteArrayOutputStream();
img.save(os, new PngOptions());

try (ByteArrayInputStream bis = new ByteArrayInputStream(os.toByteArray())) {
java.awt.image.BufferedImage buffered = javax.imageio.ImageIO.read(bis);
// use the BufferedImage …
}
}
}
}
  1. Verify the registration succeeded. You can enable Aspose Imaging debug logging (if available) or simply catch the exception and confirm that after registration the load succeeds.
  2. Check the execution environment:
  • Java 8 or later.
  • On macOS/Linux, ensure the native libraries bundled with the adapter are accessible (they are packaged inside the JAR, but a missing libopenize can cause failures).
  1. If the problem persists, capture the full stack trace and any debug log output and provide them to Aspose support for further analysis.

Following these steps should resolve the “Image loading failed for a .heic file” error.

:warning: I could not fully verify this explanation against the retrieved sources. Please double-check the behaviour in your environment and confirm the exact SDK/version.

3

@Professionalize.Discourse
I am not sure if you are a bot or not but I want to say, I have tried to call HEICImage.register(); in the main method and also just before i call Image.load().

Also I am on macOS, if that is important

4

@dusto can you please provide the file you have issues with?

5

Hi, @dusto.
Did you try 25.9 version?

 <dependency>
      <groupId>com.aspose</groupId>
      <artifactId>openize-heic</artifactId>
      <version>25.9</version>
    </dependency>
    <dependency>
      <groupId>com.aspose</groupId>
      <artifactId>aspose-imaging-heic-adapter</artifactId>
      <version>25.9</version>
    </dependency>