{"record":{"id":"6b704bdd141350a2","repo":"iOfficeAI/OfficeCLI","slug":"src-property-is-required-for-picture-type","errorCode":null,"errorMessage":"'src' property is required for picture type","messagePattern":"'src' property is required for picture type","errorType":"exception","errorClass":"ArgumentException","httpStatus":null,"severity":"error","filePath":"src/officecli/Handlers/Excel/ExcelHandler.Add.Drawings.cs","lineNumber":274,"sourceCode":"        oleObjects.AppendChild(oleObj);\n\n        SaveWorksheet(oleWorksheet);\n\n        var oleCount = oleWsElement.Descendants<OleObject>().Count();\n        return $\"/{oleSheetName}/ole[{oleCount}]\";\n    }\n\n    private string AddPicture(string parentPath, string type, InsertPosition? position, Dictionary<string, string> properties)\n    {\n        var index = position?.Index;\n        var picSegments = parentPath.TrimStart('/').Split('/', 2);\n        var picSheetName = picSegments[0];\n        var picWorksheet = FindWorksheet(picSheetName)\n            ?? throw new ArgumentException($\"Sheet not found: {picSheetName}\");\n\n        if (!properties.TryGetValue(\"path\", out var imgPath)\n            && !properties.TryGetValue(\"src\", out imgPath))\n            throw new ArgumentException(\"'src' property is required for picture type\");\n\n        // CONSISTENCY(picture-emu): use ParseAnchorBoundsEmu like OLE,\n        // so width/height accept unit-qualified strings (\"6cm\", \"2in\")\n        // in addition to bare integer cell counts.\n        var (px, py, pwEmu, phEmu) = ParseAnchorBoundsEmu(properties, \"0\", \"0\", \"5\", \"5\");\n        // P9: accept `altText=` as alias for `alt=`.\n        // CONSISTENCY(picture-alt): description completes the shared alias set.\n        var alt = properties.GetValueOrDefault(\"alt\")\n            ?? properties.GetValueOrDefault(\"altText\")\n            ?? properties.GetValueOrDefault(\"alttext\")\n            ?? properties.GetValueOrDefault(\"description\", \"\");\n\n        // Resolve the image bytes AND parse/validate the anchor BEFORE any\n        // part is created: a bad data URI or anchor used to fail after the\n        // DrawingsPart (and possibly the media blob) was already attached,\n        // leaving an empty <xdr:wsDr/> container plus orphaned xl/media\n        // bytes in the saved file even though the add reported an error.\n        var (xlImgStream, imgPartType) = OfficeCli.Core.ImageSource.Resolve(imgPath);","sourceCodeStart":256,"sourceCodeEnd":292,"githubUrl":"https://github.com/iOfficeAI/OfficeCLI/blob/1ced45e900782c5083ed550ddf328ee974e425e7/src/officecli/Handlers/Excel/ExcelHandler.Add.Drawings.cs#L256-L292","documentation":"Thrown by AddPicture when neither 'path' nor 'src' is present in the properties dictionary. The image source is mandatory; without it there is nothing to embed. Both TryGetValue('path') and TryGetValue('src') must fail for this to fire, so either key is accepted.","triggerScenarios":"Calling add /Sheet1 --type picture with no path or src property, or with a misspelled key (e.g. 'source', 'file', 'image'). The check tries 'path' first, then 'src'; both must be absent.","commonSituations":"User forgets the source property. User uses a synonym key that is not recognized ('file', 'image', 'source'). User constructs the properties dictionary programmatically and omits the key.","solutions":["Add --src /path/to/image.png (or --path) to the add call.","Verify the key name is exactly 'src' or 'path' (no alternatives like 'file' or 'image').","Ensure the image file path is valid and readable."],"exampleFix":"// before\nadd /Sheet1 --type picture\n// after\nadd /Sheet1 --type picture --src /assets/logo.png","handlingStrategy":"validation","validationCode":"// Ensure a source image path is present before calling AddPicture\nif (!properties.ContainsKey(\"path\") && !properties.ContainsKey(\"src\"))\n    throw new InvalidOperationException(\n        \"'src' (or 'path') property is required for picture type.\");","typeGuard":"static bool HasPictureSource(Dictionary<string, string> props) =>\n    props.ContainsKey(\"path\") || props.ContainsKey(\"src\");","tryCatchPattern":"try { handler.AddPicture(parentPath, type, position, properties); }\ncatch (ArgumentException ex) when (ex.Message.Contains(\"'src' property is required\"))\n{\n    Console.Error.WriteLine($\"{ex.Message} Add --src /path/to/image.png.\");\n}","preventionTips":["Always include src= or path= in every picture-add call.","Use the exact key names 'src' or 'path' (not 'file', 'image', or 'source').","Validate the properties dictionary contains a source key before the add call.","Verify the image file exists and is readable at the given path."],"tags":["excel","picture","required-property","src","validation"],"backgroundTag":null,"analyzedSha":"1ced45e900782c5083ed550ddf328ee974e425e7","analyzedAt":"2026-08-13T13:01:07.193Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}