PHPOffice/PHPWord · error · InvalidArgumentException

Invalid property '$propkey'

Error message

Invalid property '$propkey'

What it means

Field::setProperties() merges the given property map into the field's properties, but first validates each property key against the per-type 'properties' list in $fieldsArray. Any key not defined for the current field type throws InvalidArgumentException. This prevents emitting field instructions Word cannot parse.

Solutions

1. Use only property keys listed under your field's entry in Field::$fieldsArray['TYPE']['properties'].
2. Ensure setType() is called (or the type passed to the constructor) before setProperties(), since validation depends on $this->type.
3. Fix the key spelling / casing; keys are case-sensitive.
4. Catch InvalidArgumentException when properties come from external configuration.

Example fix

// before
$field->setProperties(['Format' => 'MERGEFORMAT']);
// after
$field->setProperties(['Format' => 'UPPER']);

if (!isset($allowedProps[$type])) $allowedProps = [];
$invalid = array_diff(array_keys($properties), array_keys($allowedProps[$type]));
if ($invalid) { throw new DomainException('Unknown properties: ' . implode(',', $invalid)); }

function isStringKeyedProps(array $p): bool { foreach ($p as $k => $v) { if (!is_string($k)) return false; } return true; }

try { $field->setProperties($props); } catch (\InvalidArgumentException $e) { $field->setProperties(array_intersect_key($props, $known)); }

When it happens

Trigger: Passing a properties array to new Field() or $field->setProperties(['Foo' => 'bar']) where 'Foo' is not in $fieldsArray[$this->type]['properties'], including properties valid for a different field type.

Common situations: Copying properties between field types (e.g. using \* MERGEFORMAT-style keys on a field that doesn't define them), typos like 'Formt' instead of 'Format', or setting properties before setType().

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Invalid type '$type'
• Invalid option '$optionkey', possible values are ' …
• Invalid value, on of ' . implode(', ', $position) . '…
• Invalid value, on of ' . implode(', ', $restartNumbers) . '…
• Invalid value, dirty or clean possible

AI-assisted analysis of PHPOffice/PHPWord@aef95c0415 (2026-09-14). Data as JSON: /api/errors/c77e3f3aaeb09bf9. Report an issue: GitHub.

Appendix: source

Thrown at src/PhpWord/Element/Field.php:226

     * Get Field type.
     *
     * @return string
     */
    public function getType()
    {
        return $this->type;
    }

    /**
     * Set Field properties.
     *
     * @return self
     */
    public function setProperties(array $properties = [])
    {
        foreach (array_keys($properties) as $propkey) {
            if (!(isset($this->fieldsArray[$this->type]['properties'][$propkey]))) {
                throw new InvalidArgumentException("Invalid property '$propkey'");
            }
        }
        $this->properties = array_merge($this->properties, $properties);

        return $this;
    }

    /**
     * Get Field properties.
     *
     * @return array
     */
    public function getProperties()
    {
        return $this->properties;
    }

    /**

View on GitHub (pinned to aef95c0415)