iOfficeAI/OfficeCLI · error · ArgumentException

Invalid display value ''. Expected 'icon' or 'content'.

Error message

Invalid display value ''. Expected 'icon' or 'content'.

What it means

Thrown by NormalizeOleDisplay when the 'display' property of an OLE object is null. officecli requires every OLE Add/Set call to state explicitly whether the object shows as 'icon' or 'content', so a missing/null value is rejected rather than silently defaulting. The empty quotes in the message reflect that null is rendered as an empty value. It is an ArgumentException surfaced to the caller of the Word/PPT Add or Set handlers.

Source

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

                throw new ArgumentException(
                    $"progId '{progId}' contains invalid characters. Only letters, digits, '.', '_', '-' are allowed.");
        }
    }

    /// <summary>
    /// Normalize and validate the caller-supplied <c>display</c> property
    /// for an OLE object. Canonical values are <c>"icon"</c> (show the file
    /// as a clickable icon preview) and <c>"content"</c> (show the embedded
    /// file's first page as a live picture). Any other value — including
    /// ambiguous synonyms like <c>"embed"</c>, <c>"invisible"</c>, numbers,
    /// or boolean strings — is rejected with <see cref="ArgumentException"/>
    /// so the user is told their input was wrong instead of silently
    /// falling back to "icon". Used by Word/PPT Add and Set.
    /// </summary>
    public static string NormalizeOleDisplay(string value)
    {
        if (value == null)
            throw new ArgumentException(
                "Invalid display value ''. Expected 'icon' or 'content'.");
        var v = value.Trim().ToLowerInvariant();
        if (v == "icon") return "icon";
        if (v == "content") return "content";
        throw new ArgumentException(
            $"Invalid display value '{value}'. Expected 'icon' or 'content'.");
    }

    /// <summary>
    /// Known OLE Add/Set property keys shared across Word/PPT/Excel. Used by
    /// <see cref="WarnOnUnknownOleProps"/> to surface silently-ignored
    /// properties via stderr. Kept as a single union so the three handlers
    /// stay consistent — per-handler differences (e.g. Excel's "anchor"
    /// range string) are all represented here.
    /// </summary>
    private static readonly HashSet<string> KnownOleProps = new(StringComparer.OrdinalIgnoreCase)
    {
        "src", "path", "progId", "progid",

View on GitHub (pinned to 1ced45e900)

Solutions

1. Set properties["display"] = "icon" (or "content") before calling the Add/Set handler.
2. If your script intends a default, normalize before the call: var display = myDisplay ?? "icon".
3. Audit the property-dictionary construction site to guarantee display is always populated.

Example fix

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

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

if (!props.ContainsKey("display") || props["display"] == null)
    props["display"] = "icon"; // or "content"

static bool HasOleDisplay(Dictionary<string,string> p)
    => p.TryGetValue("display", out var v) && v != null;

try { NormalizeOleDisplay(props["display"]); }
catch (ArgumentException ex) when (ex.Message.Contains("display value"))
{ /* default to icon and warn */ }

When it happens

Trigger: Calling an OLE Add/Set handler with a properties dictionary that omits the 'display' key, or passes display=null. Happens when a script builds the property bag conditionally and skips display for certain branches.

Common situations: Migrating from an older API that defaulted display to 'icon'; building the property dictionary from a config file that has no display field; deserializing JSON where display was omitted (yielding null) instead of an empty string.

Related errors

• 'src' property is required for ole type
• 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/e0483f005ebef1b9. Report an issue: GitHub.