mudler/LocalAI · error

-1

-1

Error message

[sam3-cpp] PCS mode requires full SAM 3 model\n

What it means

The sam3-cpp shim only supports Promptable Concept Segmentation (PCS, text-prompt driven) on the full SAM 3 model, which includes the text encoder. sam3_is_visual_only() or a model type other than SAM3_MODEL_SAM3 (e.g. an image-encoder-only checkpoint) triggers this message and a -1 return with no detections. Use promptable visual segmentation (PVS with points/boxes) with visual-only checkpoints.

Source

Thrown at backend/go/sam3-cpp/cpp/gosam3.cpp:128

        pvs_params.box = {boxes[0], boxes[1], boxes[2], boxes[3]};
        pvs_params.use_box = true;
    }

    g_result = sam3_segment_pvs(*g_state, *g_model, pvs_params);
    encode_masks_as_png();

    return static_cast<int>(g_result.detections.size());
}

int sam3_cpp_segment_pcs(const char *text_prompt, float threshold) {
    if (!g_model || !g_state) {
        return -1;
    }

    // PCS mode requires SAM 3 (full model with text encoder)
    if (sam3_is_visual_only(*g_model) ||
        sam3_get_model_type(*g_model) != SAM3_MODEL_SAM3) {
        fprintf(stderr, "[sam3-cpp] PCS mode requires full SAM 3 model\n");
        return -1;
    }

    sam3_pcs_params pcs_params;
    pcs_params.text_prompt = text_prompt;
    pcs_params.score_threshold = threshold > 0 ? threshold : 0.5f;

    g_result = sam3_segment_pcs(*g_state, *g_model, pcs_params);
    encode_masks_as_png();

    return static_cast<int>(g_result.detections.size());
}

int sam3_cpp_get_n_detections(void) {
    return static_cast<int>(g_result.detections.size());
}

float sam3_cpp_get_detection_x(int i) {

View on GitHub (pinned to 44413a9d06)

Solutions

1. Load the full SAM 3 model (with text encoder) if you need PCS/text-prompt segmentation
2. Switch to PVS mode (sam3_cpp_segment_pvs with points or boxes) if you must use the visual-only checkpoint
3. Check the model file/type in your gallery YAML matches the full SAM 3 build before selecting PCS in requests

Example fix

// before
sam3_cpp_load("sam3-vit-visual-only.gguf", "cpu");
int n = sam3_cpp_segment_pcs("a dog", 0.5f); // returns -1

// after: use visual prompting with the visual-only checkpoint
float pts[] = {x, y, 0.0f /*neg*/};
int n = sam3_cpp_segment_pvs(pts, 1, nullptr, 0, 0.5f);

// Go caller: only offer text-prompt (PCS) requests for full SAM 3 models
if modelConfig.Type == "visual-only" && req.TextPrompt != "" {
    return fmt.Errorf("text-prompt segmentation requires the full SAM 3 model; use point/box prompting instead")
}

When it happens

Trigger: Loading a visual-only / encoder-only SAM 3 checkpoint and then calling sam3_cpp_segment_pcs(text_prompt, threshold). The check fires before any inference runs, so g_result is untouched.

Common situations: Downloading the smaller 'visual' SAM 3 weights to save disk/memory and then trying text-prompt segmentation; mixing up SAM3 model variants (ViT visual-only vs full) in a model gallery config.

Related errors

• 3
• engine_args must be a JSON object, got {type(extra).__name__
• unknown engine_args key {key!r}.{hint}
• ced: dlopen %q: %w
• face-detect: dlopen %q: %w

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