mudler/LocalAI · error

Reference image must have at least 3 channels, got %d\n

Error message

Reference image must have at least 3 channels, got %d\n

What it means

The reference image has fewer than 3 channels (e.g. grayscale). Guard: convert single-channel images to RGB or reject them up front with a validation error naming the channel count.

Source

Thrown at backend/go/stablediffusion-ggml/cpp/gosd.cpp:949

        fprintf(stderr, "Loading %d reference images\n", ref_images_count);

        for (int i = 0; i < ref_images_count; i++) {
            if (ref_images[i] == NULL || strlen(ref_images[i]) == 0) {
                continue;
            }

            fprintf(stderr, "Loading reference image %d: %s\n", i + 1, ref_images[i]);

            int c = 0;
            int ref_width = 0;
            int ref_height = 0;
            uint8_t* ref_image_buffer = stbi_load(ref_images[i], &ref_width, &ref_height, &c, 3);
            if (ref_image_buffer == NULL) {
                fprintf(stderr, "Failed to load reference image from '%s'\n", ref_images[i]);
                continue;
            }
            if (c < 3) {
                fprintf(stderr, "Reference image must have at least 3 channels, got %d\n", c);
                free(ref_image_buffer);
                continue;
            }

            // Resize reference image if dimensions don't match
            if (ref_width != width || ref_height != height) {
                fprintf(stderr, "Resizing reference image from %dx%d to %dx%d\n", ref_width, ref_height, width, height);

                uint8_t* resized_ref_buffer = (uint8_t*)malloc(height * width * 3);
                if (resized_ref_buffer == NULL) {
                    fprintf(stderr, "Failed to allocate memory for resized reference image\n");
                    free(ref_image_buffer);
                    continue;
                }

                stbir_resize(ref_image_buffer, ref_width, ref_height, 0,
                             resized_ref_buffer, width, height, 0, STBIR_TYPE_UINT8,
                             3, STBIR_ALPHA_CHANNEL_NONE, 0,

View on GitHub (pinned to 44413a9d06)

Solutions

1. Convert the reference image to RGB/RGBA (at least 3 channels) before submitting.
2. Avoid grayscale or single-channel images as reference input.

When it happens

Trigger: Thrown at backend/go/stablediffusion-ggml/cpp/gosd.cpp:949 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of mudler/LocalAI@44413a9d06 (2026-08-15). Data as JSON: /api/errors/f115b306cc40b2b9. Report an issue: GitHub.