iOfficeAI/OfficeCLI · error · ArgumentException

progId '{progId}' contains invalid characters. Only letters,

Error message

progId '{progId}' contains invalid characters. Only letters, digits, '.', '_', '-' are allowed.

What it means

Thrown by OleHelper.ValidateProgId when a progId string contains any character outside the COM-allowed set: letters, digits, '.', '_', '-'. Characters like '<', '>', '&', '"', spaces, or other punctuation are rejected because they would either corrupt the OOXML progId attribute (XML-unsafe characters) or be rejected by Office on reopen. The check iterates every character after the length and digit-start checks pass.

Source

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

    /// </summary>
    public static void ValidateProgId(string progId)
    {
        if (progId == null) return;
        if (progId.Length > 39)
            throw new ArgumentException(
                $"progId '{progId}' exceeds 39 characters (limit: 39, actual: {progId.Length}).");
        if (progId.Length > 0 && char.IsDigit(progId[0]))
            throw new ArgumentException(
                $"progId '{progId}' cannot start with a digit.");
        // COM ProgID character set: letters, digits, '.', '_', '-'. Anything
        // else (notably XML-unsafe characters like '<', '>', '&', '"') would
        // either corrupt the OOXML progId attribute or be rejected by Office
        // on reopen. Reject early with an actionable error instead of letting
        // bad bytes land in the package.
        foreach (var ch in progId)
        {
            if (!(char.IsLetterOrDigit(ch) || ch == '.' || ch == '_' || ch == '-'))
                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(

View on GitHub (pinned to 1ced45e900)

Solutions

Remove or replace invalid characters: use only letters, digits, '.', '_', and '-'.
Replace spaces with underscores or dots (e.g. 'My_ProgId' or 'My.ProgId').
Strip XML-unsafe characters (<, >, &, ", ') entirely from the progId.
Use a standard Office progId which is guaranteed to be clean.

Example fix

// before — contains spaces and special chars
add ole src=file.pdf progId='My App & Doc' path='/body'

// after — clean progId with only allowed chars
add ole src=file.pdf progId=MyApp.Doc path='/body'

Defensive patterns

Strategy: validation

Validate before calling

// Pre-validate progId character set
if (!string.IsNullOrEmpty(progId))
{
    foreach (char ch in progId)
    {
        if (!(char.IsLetterOrDigit(ch) || ch == '.' || ch == '_' || ch == '-'))
        {
            Console.Error.WriteLine($"progId '{progId}' contains invalid char '{ch}'. Only letters, digits, '.', '_', '-' allowed.");
            // Sanitize: replace invalid chars with '_'
            progId = new string(progId.Select(c => (char.IsLetterOrDigit(c) || c=='.'||c=='_'||c=='-') ? c : '_').ToArray());
            break;
        }
    }
}
OleHelper.ValidateProgId(progId);

Try / catch

try
{
    OleHelper.ValidateProgId(progId);
}
catch (ArgumentException ex) when (ex.Message.Contains("invalid characters"))
{
    // Sanitize: replace invalid chars with '_' and retry
    progId = new string(progId.Select(c => (char.IsLetterOrDigit(c) || c=='.'||c=='_'||c=='-') ? c : '_').ToArray());
    OleHelper.ValidateProgId(progId);
}

Prevention

Construct progIds from only letters, digits, '.', '_', and '-'.
When deriving progIds from filenames or user input, sanitize by replacing invalid characters with '_' or '.'.
Avoid spaces, XML-unsafe characters (<, >, &, ", '), and other punctuation in progIds.
Use standard Office progIds (which are always clean) when a custom identifier isn't required.

When it happens

Trigger: Calling Add ole or Set ole with a progId containing spaces (e.g. 'My Prog Id'), XML-unsafe characters ('Doc<Name>'), ampersands ('A&B'), quotes ('My"Id'), or any other punctuation not in {letter, digit, '.', '_', '-'}. The foreach loop over each character rejects the first invalid one it finds.

Common situations: A progId auto-generated from a filename with spaces or special characters. A copy-paste from a rich text source that introduced invisible or special characters. A user who included a description instead of a clean identifier. An adversarial input attempting to inject XML via the progId attribute.

Understand the failure class

Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

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