iOfficeAI/OfficeCLI · error · ArgumentException

'src' property is required for ole type

Error message

'src' property is required for ole type

What it means

Thrown by RequireSource when neither the 'src' nor the 'path' key exists in the OLE property dictionary. An OLE object must reference an embedded file, so a missing source is a hard error rather than a no-op. Both 'src' and 'path' are accepted as aliases for the same field.

Source

Thrown at src/officecli/Core/OleHelper.cs:603

    }

    // ==================== Shared Add helpers ====================
    //
    // The following methods extract duplicated boilerplate that previously
    // appeared verbatim in Word/Excel/PowerPoint AddOle handlers.

    /// <summary>
    /// Validate and extract the required <c>src</c> (or <c>path</c>) property
    /// from the caller-supplied dictionary. Throws
    /// <see cref="ArgumentException"/> when neither key is present or the
    /// value is blank.
    /// </summary>
    public static string RequireSource(Dictionary<string, string>? properties)
    {
        properties ??= new Dictionary<string, string>();
        if (!properties.TryGetValue("src", out var srcPath)
            && !properties.TryGetValue("path", out srcPath))
            throw new ArgumentException("'src' property is required for ole type");
        if (string.IsNullOrWhiteSpace(srcPath))
            throw new ArgumentException("'src' property for ole type cannot be empty");
        return srcPath;
    }

    /// <summary>
    /// Resolve the ProgID from explicit property → auto-detected from
    /// extension, then validate. Replaces the 4-line fallback chain that
    /// was duplicated in every handler.
    /// </summary>
    public static string ResolveProgId(Dictionary<string, string> properties, string srcPath)
    {
        var progId = properties.GetValueOrDefault("progId")
            ?? properties.GetValueOrDefault("progid")
            ?? DetectProgId(srcPath);
        ValidateProgId(progId);
        return progId;
    }

View on GitHub (pinned to 1ced45e900)

Solutions

1. Add properties["src"] = filePath (or "path") before the Add call.
2. Verify the key spelling — only 'src' and 'path' are recognized.
3. If the path comes from user input, validate it is non-null before adding the key.

Example fix

// before
var props = new Dictionary<string,string> { ["display"] = "icon" };
AddOle(props); // throws 282 — no src/path

// after
var props = new Dictionary<string,string>
{
    ["src"] = filePath,
    ["display"] = "icon"
};
AddOle(props);

if (!props.ContainsKey("src") && !props.ContainsKey("path"))
    throw new InvalidOperationException("OLE object needs a src/path");

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

try { RequireSource(props); }
catch (ArgumentException ex) when (ex.Message.Contains("required"))
{ /* prompt user for file path */ }

When it happens

Trigger: Building a properties dictionary for an OLE Add but forgetting to include the file path; using a wrong key name like 'source' or 'file'.

Common situations: Renaming keys during a refactor and missing the OLE path; reading path from a variable that was null so the key never got added; copy-paste from a non-OLE shape spec that uses different keys.

Related errors

• Invalid display value ''. Expected 'icon' or 'content'.
• Invalid display value '{value}'. Expected 'icon' or 'content
• 'src' property for ole type cannot be empty
• Invalid color value: '{original}'. RGB percentage components
• Invalid color value: '{original}'. RGB components must be 0-

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