iOfficeAI/OfficeCLI · error · ArgumentException

'src' property is required for picture type

Error message

'src' property is required for picture type

What it means

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.

Source

Thrown at src/officecli/Handlers/Excel/ExcelHandler.Add.Drawings.cs:274

        oleObjects.AppendChild(oleObj);

        SaveWorksheet(oleWorksheet);

        var oleCount = oleWsElement.Descendants<OleObject>().Count();
        return $"/{oleSheetName}/ole[{oleCount}]";
    }

    private string AddPicture(string parentPath, string type, InsertPosition? position, Dictionary<string, string> properties)
    {
        var index = position?.Index;
        var picSegments = parentPath.TrimStart('/').Split('/', 2);
        var picSheetName = picSegments[0];
        var picWorksheet = FindWorksheet(picSheetName)
            ?? throw new ArgumentException($"Sheet not found: {picSheetName}");

        if (!properties.TryGetValue("path", out var imgPath)
            && !properties.TryGetValue("src", out imgPath))
            throw new ArgumentException("'src' property is required for picture type");

        // CONSISTENCY(picture-emu): use ParseAnchorBoundsEmu like OLE,
        // so width/height accept unit-qualified strings ("6cm", "2in")
        // in addition to bare integer cell counts.
        var (px, py, pwEmu, phEmu) = ParseAnchorBoundsEmu(properties, "0", "0", "5", "5");
        // P9: accept `altText=` as alias for `alt=`.
        // CONSISTENCY(picture-alt): description completes the shared alias set.
        var alt = properties.GetValueOrDefault("alt")
            ?? properties.GetValueOrDefault("altText")
            ?? properties.GetValueOrDefault("alttext")
            ?? properties.GetValueOrDefault("description", "");

        // Resolve the image bytes AND parse/validate the anchor BEFORE any
        // part is created: a bad data URI or anchor used to fail after the
        // DrawingsPart (and possibly the media blob) was already attached,
        // leaving an empty <xdr:wsDr/> container plus orphaned xl/media
        // bytes in the saved file even though the add reported an error.
        var (xlImgStream, imgPartType) = OfficeCli.Core.ImageSource.Resolve(imgPath);

View on GitHub (pinned to 1ced45e900)

Solutions

1. Add --src /path/to/image.png (or --path) to the add call.
2. Verify the key name is exactly 'src' or 'path' (no alternatives like 'file' or 'image').
3. Ensure the image file path is valid and readable.

Example fix

// before
add /Sheet1 --type picture
// after
add /Sheet1 --type picture --src /assets/logo.png

// Ensure a source image path is present before calling AddPicture
if (!properties.ContainsKey("path") && !properties.ContainsKey("src"))
    throw new InvalidOperationException(
        "'src' (or 'path') property is required for picture type.");

static bool HasPictureSource(Dictionary<string, string> props) =>
    props.ContainsKey("path") || props.ContainsKey("src");

try { handler.AddPicture(parentPath, type, position, properties); }
catch (ArgumentException ex) when (ex.Message.Contains("'src' property is required"))
{
    Console.Error.WriteLine($"{ex.Message} Add --src /path/to/image.png.");
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Property 'sqref' (or 'range'/'ref') is required for validati
• Chart requires a 'data' property. Use: data="Series1:1,2,3;S
• Sheet not found: {picSheetName}
• Invalid anchor: '{picAnchorRaw}'. Expected e.g. 'B2', 'B2:E6
• Property 'ref' is required for comment

AI-assisted analysis of iOfficeAI/OfficeCLI@1ced45e900 (2026-08-13). Data as JSON: /api/errors/6b704bdd141350a2. Report an issue: GitHub.