Yalantis/uCrop · error · CImgArgumentException

load_yuv(): Specified chroma subsampling %u is invalid, for

Error message

load_yuv(): Specified chroma subsampling %u is invalid, for file '%s'.

What it means

load_yuv() only supports the chroma subsampling schemes 4:2:0, 4:2:2 and 4:4:4, which define how U/V planes are laid out in the raw stream. Any other value is rejected with CImgArgumentException before any I/O, since plane sizes (cfx/cfy) would be undefined.

Source

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

                                    const unsigned int size_x, const unsigned int size_y=1,
                                    const unsigned int chroma_subsampling=444,
                                    const unsigned int first_frame=0, const unsigned int last_frame=~0U,
                                    const unsigned int step_frame=1, const bool yuv2rgb=true) {
      return CImgList<T>().load_yuv(file,size_x,size_y,chroma_subsampling,
                                    first_frame,last_frame,step_frame,yuv2rgb);
    }

    CImgList<T>& _load_yuv(std::FILE *const file, const char *const filename,
                           const unsigned int size_x, const unsigned int size_y,
                           const unsigned int chroma_subsampling,
                           const unsigned int first_frame, const unsigned int last_frame,
                           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");

View on GitHub (pinned to f788b534b4)

Solutions

1. Pass the actual scheme of your file: 420 (most common, e.g. I420), 422, or 444
2. If the parameter was accidentally 0/default, supply it explicitly
3. Determine the subsampling with ffprobe (e.g. `ffprobe -pix_fmt file.yuv` context) and map pix_fmt to the scheme: yuv420p->420, yuv422p->422, yuv444p->444

Example fix

// before
imgs.load_yuv("video.yuv", 640, 480); // chroma defaults to 0
// after
imgs.load_yuv("video.yuv", 640, 480, 420); // I420 raw stream

unsigned int cs = /* configured */;
if (cs != 420 && cs != 422 && cs != 444) { /* reject config / map from pix_fmt first */ }

bool validChromaSubsampling(unsigned int cs) { return cs == 420 || cs == 422 || cs == 444; }

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

When it happens

Trigger: Calling load_yuv(filename, w, h, chroma_subsampling, ...) with chroma_subsampling set to anything other than 420, 422, or 444 - e.g. 0 (default-initialized/omitted), 411, 440, or a percent-like value 50.

Common situations: Forgetting the parameter so it defaults to 0; guessing the subsampling of a raw YUV dump; confusing 4:2:0 vs 4:2:2 layout conventions (I420/YV12 vs YUY2) or passing a codec fourcc instead of the numeric scheme.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• load_yuv(): Specified dimensions (%u,%u) are invalid, for fi
• haar(): Invalid specified axis '%c' (should be { x | y | z }
• load_yuv(): Specified filename is (null).
• load_yuv(): File '%s' doesn't contain frame number %u.
• load_yuv() : Missing data in file '%s'.

AI-assisted analysis of Yalantis/uCrop@f788b534b4 (2026-09-08). Data as JSON: /api/errors/736b22acdfc10240. Report an issue: GitHub.