symfony/polyfill-mbstring · error · ValueError

mb_str_pad(): Argument #3 ($pad_string) must be a non-empty…

Error message

mb_str_pad(): Argument #3 ($pad_string) must be a non-empty string

What it means

Mbstring::mb_str_pad() throws this ValueError when $pad_string is an empty string, because padding with an empty string is impossible. This mirrors native PHP 8.3 mb_str_pad behavior; on PHP < 8.0 the polyfill triggers an E_USER_WARNING and returns false instead.

Solutions

  1. Pass a non-empty $pad_string (omit the argument to use the default ' ')
  2. Default empty values: $pad ?: ' ' before calling
  3. Validate configured pad strings are non-empty at load time
  4. Catch \ValueError (PHP 8+) or detect the E_USER_WARNING/false (PHP < 8)

Example fix

// before
mb_str_pad($label, 10, $padChar); // $padChar may be ''
// after
mb_str_pad($label, 10, $padChar !== '' ? $padChar : ' ');
Defensive patterns

Strategy: validation

Validate before calling

if (!is_string($padString) || $padString === '') {
    $padString = ' ';
}
mb_str_pad($string, $length, $padString, $padType, $encoding);

Type guard

function isNonEmptyString($value): bool
{
    return is_string($value) && $value !== '';
}

Try / catch

try {
    $padded = mb_str_pad($s, $len, $padString);
} catch (\ValueError $e) {
    $padded = mb_str_pad($s, $len);
}

Prevention

When it happens

Trigger: Calling mb_str_pad($s, $len, '') or with a $pad_string argument that is an empty string — often from an empty config/template value or an empty substring used as the pad string.

Common situations: Pad string coming from a config value or language file that was left empty; code computing the pad string dynamically (e.g. substr result) that yields ''; default-parameter misuse where the caller explicitly passed '' thinking it means 'default'.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

AI-assisted analysis of symfony/polyfill-mbstring@d3d318bad5 (2026-09-13). Data as JSON: /api/errors/85e3e235b1750065. Report an issue: GitHub.

Appendix: source

Thrown at Mbstring.php:903

    }

    /** @return string|false */
    public static function mb_str_pad(string $string, int $length, string $pad_string = ' ', int $pad_type = \STR_PAD_RIGHT, ?string $encoding = null)
    {
        if (null === $encoding) {
            $encoding = self::mb_internal_encoding();
        } elseif (!self::assertEncoding($encoding, 'mb_str_pad(): Argument #5 ($encoding) must be a valid encoding, "%s" given')) {
            return false;
        }

        if (self::mb_strlen($pad_string, $encoding) <= 0) {
            if (\PHP_VERSION_ID < 80000) {
                trigger_error('mb_str_pad(): Argument #3 ($pad_string) must be a non-empty string', \E_USER_WARNING);

                return false;
            }

            throw new \ValueError('mb_str_pad(): Argument #3 ($pad_string) must be a non-empty string');
        }

        if (!\in_array($pad_type, [\STR_PAD_RIGHT, \STR_PAD_LEFT, \STR_PAD_BOTH], true)) {
            if (\PHP_VERSION_ID < 80000) {
                trigger_error('mb_str_pad(): Argument #4 ($pad_type) must be STR_PAD_LEFT, STR_PAD_RIGHT, or STR_PAD_BOTH', \E_USER_WARNING);

                return false;
            }

            throw new \ValueError('mb_str_pad(): Argument #4 ($pad_type) must be STR_PAD_LEFT, STR_PAD_RIGHT, or STR_PAD_BOTH');
        }

        $paddingRequired = $length - self::mb_strlen($string, $encoding);

        if ($paddingRequired < 1) {
            return $string;
        }

View on GitHub (pinned to d3d318bad5)