Yalantis/uCrop · error · CImgArgumentException

load_yuv(): Specified dimensions (%u,%u) are invalid, for fi

Error message

load_yuv(): Specified dimensions (%u,%u) are invalid, for file '%s'.

What it means

For the given subsampling, chroma planes are stored at size_x/cfx by size_y/cfy; this only works when the luma dimensions are divisible by cfx/cfy (2 for 420/422 horizontally, 2 for 420 vertically). Dimensions must also be nonzero. CImg validates this up front and throws CImgArgumentException.

Source

Thrown at ucrop/src/main/jni/CImg.h:67208

                           const unsigned int step_frame, const bool yuv2rgb) {
      if (!filename && !file)
        throw CImgArgumentException(_cimglist_instance
                                    "load_yuv(): Specified filename is (null).",
                                    cimglist_instance);
      if (chroma_subsampling!=420 && chroma_subsampling!=422 && chroma_subsampling!=444)
        throw CImgArgumentException(_cimglist_instance
                                    "load_yuv(): Specified chroma subsampling %u is invalid, for file '%s'.",
                                    cimglist_instance,
                                    chroma_subsampling,filename?filename:"(FILE*)");
      const unsigned int
        cfx = chroma_subsampling==420 || chroma_subsampling==422?2:1,
        cfy = chroma_subsampling==420?2:1,
        nfirst_frame = first_frame<last_frame?first_frame:last_frame,
        nlast_frame = first_frame<last_frame?last_frame:first_frame,
        nstep_frame = step_frame?step_frame:1;

      if (!size_x || !size_y || size_x%cfx || size_y%cfy)
        throw CImgArgumentException(_cimglist_instance
                                    "load_yuv(): Specified dimensions (%u,%u) are invalid, for file '%s'.",
                                    cimglist_instance,
                                    size_x,size_y,filename?filename:"(FILE*)");

      CImg<ucharT> YUV(size_x,size_y,1,3), UV(size_x/cfx,size_y/cfy,1,2);
      std::FILE *const nfile = file?file:cimg::fopen(filename,"rb");
      bool stop_flag = false;
      int err;
      if (nfirst_frame) {
        err = cimg::fseek(nfile,(uint64T)nfirst_frame*(YUV._width*YUV._height + 2*UV._width*UV._height),SEEK_CUR);
        if (err) {
          if (!file) cimg::fclose(nfile);
          throw CImgIOException(_cimglist_instance
                                "load_yuv(): File '%s' doesn't contain frame number %u.",
                                cimglist_instance,
                                filename?filename:"(FILE*)",nfirst_frame);
        }
      }

View on GitHub (pinned to f788b534b4)

Solutions

  1. Use the real even dimensions of the stream (e.g. 854x480 instead of 853x480; raw YUV streams are effectively padded to even sizes)
  2. Swap width/height if they were reversed (landscape/portrait mix-up)
  3. Ensure nonzero, actual pixel dimensions are passed - check the variable initialization
  4. If the source is truly odd-sized, pre-pad it (e.g. via ffmpeg -vf pad=ceil(iw/2)*2:ceil(ih/2)*2) and use the padded size

Example fix

// before
imgs.load_yuv("video.yuv", 853, 480, 420); // 853 % 2 != 0
// after
imgs.load_yuv("video.yuv", 854, 480, 420); // even dimensions
Defensive patterns

Strategy: validation

Validate before calling

unsigned int cfx = (cs == 420 || cs == 422) ? 2 : 1, cfy = (cs == 420) ? 2 : 1;
if (w == 0 || h == 0 || w % cfx || h % cfy) { /* pad/reject before loading */ }

Type guard

bool validYuvSize(unsigned int w, unsigned int h, unsigned int cs) {
  unsigned int cfx = (cs==420||cs==422)?2:1, cfy = cs==420?2:1;
  return w && h && w % cfx == 0 && h % cfy == 0;
}

Try / catch

try { imgs.load_yuv(path, w, h, cs); }
catch (CImgArgumentException& e) { fprintf(stderr, "bad YUV dimensions %ux%u: %s\n", w, h, e.what()); }

Prevention

When it happens

Trigger: load_yuv(filename, w, h, cs, ...) where size_x or size_y is 0, or size_x % cfx != 0 / size_y % cfy != 0 - e.g. 853x480 with 420 (853 not divisible by 2), or any odd width with 422.

Common situations: Odd-resolution video encodes (common with H.264 crops to 853x480, 1279x720); swapped width/height arguments; passing frame counts or byte sizes instead of pixel dimensions; zero dimensions from an uninitialized variable.

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 Yalantis/uCrop@f788b534b4 (2026-09-08). Data as JSON: /api/errors/16485fd0a246826d. Report an issue: GitHub.