{"record":{"id":"c710a9435e8a2e46","repo":"mudler/LocalAI","slug":"1-c710a9","errorCode":"-1","errorMessage":"[sam3-cpp] PCS mode requires full SAM 3 model\\n","messagePattern":"\\[sam3-cpp\\] PCS mode requires full SAM 3 model\\\\n","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"backend/go/sam3-cpp/cpp/gosam3.cpp","lineNumber":128,"sourceCode":"        pvs_params.box = {boxes[0], boxes[1], boxes[2], boxes[3]};\n        pvs_params.use_box = true;\n    }\n\n    g_result = sam3_segment_pvs(*g_state, *g_model, pvs_params);\n    encode_masks_as_png();\n\n    return static_cast<int>(g_result.detections.size());\n}\n\nint sam3_cpp_segment_pcs(const char *text_prompt, float threshold) {\n    if (!g_model || !g_state) {\n        return -1;\n    }\n\n    // PCS mode requires SAM 3 (full model with text encoder)\n    if (sam3_is_visual_only(*g_model) ||\n        sam3_get_model_type(*g_model) != SAM3_MODEL_SAM3) {\n        fprintf(stderr, \"[sam3-cpp] PCS mode requires full SAM 3 model\\n\");\n        return -1;\n    }\n\n    sam3_pcs_params pcs_params;\n    pcs_params.text_prompt = text_prompt;\n    pcs_params.score_threshold = threshold > 0 ? threshold : 0.5f;\n\n    g_result = sam3_segment_pcs(*g_state, *g_model, pcs_params);\n    encode_masks_as_png();\n\n    return static_cast<int>(g_result.detections.size());\n}\n\nint sam3_cpp_get_n_detections(void) {\n    return static_cast<int>(g_result.detections.size());\n}\n\nfloat sam3_cpp_get_detection_x(int i) {","sourceCodeStart":110,"sourceCodeEnd":146,"githubUrl":"https://github.com/mudler/LocalAI/blob/44413a9d06bf5bc52ce088ba8ca74e5a2e8bee26/backend/go/sam3-cpp/cpp/gosam3.cpp#L110-L146","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Load the full SAM 3 model (with text encoder) if you need PCS/text-prompt segmentation","Switch to PVS mode (sam3_cpp_segment_pvs with points or boxes) if you must use the visual-only checkpoint","Check the model file/type in your gallery YAML matches the full SAM 3 build before selecting PCS in requests"],"exampleFix":"// before\nsam3_cpp_load(\"sam3-vit-visual-only.gguf\", \"cpu\");\nint n = sam3_cpp_segment_pcs(\"a dog\", 0.5f); // returns -1\n\n// after: use visual prompting with the visual-only checkpoint\nfloat pts[] = {x, y, 0.0f /*neg*/};\nint n = sam3_cpp_segment_pvs(pts, 1, nullptr, 0, 0.5f);","handlingStrategy":"validation","validationCode":"// Go caller: only offer text-prompt (PCS) requests for full SAM 3 models\nif modelConfig.Type == \"visual-only\" && req.TextPrompt != \"\" {\n    return fmt.Errorf(\"text-prompt segmentation requires the full SAM 3 model; use point/box prompting instead\")\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Record whether the loaded checkpoint is visual-only or full SAM 3 at load time and route requests accordingly","Expose PVS (points/boxes) as the documented path for visual-only checkpoints","Treat a -1 return from segment_pcs as 'mode unsupported', not as 'zero detections'"],"tags":["sam3","pcs","model-type","backend"],"backgroundTag":null,"analyzedSha":"44413a9d06bf5bc52ce088ba8ca74e5a2e8bee26","analyzedAt":"2026-08-15T10:13:50.291Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}