What causes "JPEG sampling factors must be 1..4 " in DrKLO/Telegram?

Use only values 1-4 for both horizontal and vertical sampling factors.

JPEG sampling factors must be 1..4

Error message

JPEG sampling factors must be 1..4

What it means

The set_sample_factors function processes the -sample argument, which sets horizontal and vertical sampling factors per component. JPEG sampling factors must be in the range 1..4. If any factor value is <= 0 or > 4, the function reports this error and returns FALSE. Sampling factors control chroma subsampling (e.g., 2x2 for 4:2:0, 2x1 for 4:2:2).

Source

Thrown at TMessagesProj/jni/mozjpeg/rdswitch.c:624

GLOBAL(boolean)
set_sample_factors (j_compress_ptr cinfo, char *arg)
/* Process a sample-factors parameter string, of the form
 *     HxV[,HxV,...]
 * If there are more components than parameters, "1x1" is assumed for the rest.
 */
{
  int ci, val1, val2;
  char ch1, ch2;

  for (ci = 0; ci < MAX_COMPONENTS; ci++) {
    if (*arg) {
      ch2 = ',';                /* if not set by sscanf, will be ',' */
      if (sscanf(arg, "%d%c%d%c", &val1, &ch1, &val2, &ch2) < 3)
        return FALSE;
      if ((ch1 != 'x' && ch1 != 'X') || ch2 != ',') /* syntax check */
        return FALSE;
      if (val1 <= 0 || val1 > 4 || val2 <= 0 || val2 > 4) {
        fprintf(stderr, "JPEG sampling factors must be 1..4\n");
        return FALSE;
      }
      cinfo->comp_info[ci].h_samp_factor = val1;
      cinfo->comp_info[ci].v_samp_factor = val2;
      while (*arg && *arg++ != ',');  /* advance to next segment of arg
                                         string */
    } else {
      /* reached end of parameter, set remaining components to 1x1 sampling */
      cinfo->comp_info[ci].h_samp_factor = 1;
      cinfo->comp_info[ci].v_samp_factor = 1;
    }
  }
  return TRUE;
}

View on GitHub (pinned to 45ab8f4308)

Solutions

Use only values 1-4 for both horizontal and vertical sampling factors.
Common settings: 2x2 (4:2:0 subsampling), 2x1 (4:2:2), 1x1 (no subsampling).
For grayscale or high quality, use 1x1.

Example fix

# before
cjpeg -sample 5x1 image.bmp > out.jpg
# after
cjpeg -sample 2x2 image.bmp > out.jpg

Defensive patterns

Strategy: validation

Validate before calling

// Pre-validate sample factors argument before calling set_sample_factors
static boolean validate_sample_arg(const char *arg) {
  const char *p = arg;
  while (*p) {
    int v1, v2; char c1, c2 = ',';
    if (sscanf(p, "%d%c%d%c", &v1, &c1, &v2, &c2) < 3) return FALSE;
    if ((c1 != 'x' && c1 != 'X')) return FALSE;
    if (v1 < 1 || v1 > 4 || v2 < 1 || v2 > 4) return FALSE;
    while (*p && *p++ != ',') ;
  }
  return TRUE;
}

Prevention

Use only sampling factors in the range 1-4 for both H and V.
Common values: 2x2 (4:2:0), 2x1 (4:2:2), 1x1 (no subsampling).
Use 'x' or 'X' as the separator between horizontal and vertical factors.
Separate multi-component factors with commas.

When it happens

Trigger: Passing -sample with a factor outside 1..4: 'cjpeg -sample 5x1 image.bmp' or '-sample 0x2' or negative values. The sscanf parses val1/val2 and the bounds check val1 <= 0 || val1 > 4 fires.

Common situations: Typo in the sampling factor string; misunderstanding the valid range; attempting to use extreme subsampling; passing a quality-related number instead of a sampling factor; wrong separator (the format requires 'x' or 'X' between H and V).

Related errors

AI-assisted analysis of DrKLO/Telegram@45ab8f4308 (2026-08-14). Data as JSON: /api/errors/a4387c9ffa521a65. Report an issue: GitHub.