symfony/process · error · InvalidArgumentException

Command line is missing a value for parameter

Error message

Command line is missing a value for parameter "%s": 

What it means

Process supports escaped env placeholders like "${:VAR}" in the command line. replacePlaceholders() substitutes them at start(); if the referenced env variable is unset or false, an InvalidArgumentException naming the parameter and full command line is thrown.

Solutions

1. Ensure the env variable is set and not false before start(): $env['MY_VAR'] ?? throw or default
2. Fix the placeholder name to match an existing env key
3. Use getenv()/$_ENV checks or provide a default in the env array passed to start()

Example fix

// before
$process->start(['FOO' => null]); // command contains "${:FOO}"
// after
$process->start(['FOO' => 'bar']); // or remove "${:FOO}" from the command

foreach ($placeholders as $name) {
    if (!isset($env[$name]) || $env[$name] === false) {
        throw new InvalidArgumentException("Missing env for placeholder {$name}");
    }
}
$process->start($env);

try { $process->start($env); } catch (InvalidArgumentException $e) { /* report missing env var from message */ }

When it happens

Trigger: Starting a process whose command contains "${:MY_VAR}" while MY_VAR is absent (or explicitly false) in the env array passed to start()/Process.

Common situations: Missing env vars in CI/local environments, typo between the placeholder name and env key, env var explicitly set to false which the guard treats as missing.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• Invalid option " " passed to " ()". Supported options are "…
• Setting ignored signals while the process is running is not…
• Output has been disabled.
• The timeout value must be a valid positive integer or float…
• Cannot send signal on a non running process.

AI-assisted analysis of symfony/process@99b85026db (2026-09-14). Data as JSON: /api/errors/9ea83ddfe9b0e0a4. Report an issue: GitHub.

Appendix: source

Thrown at Process.php:1703

        if (str_contains($argument, "\0")) {
            $argument = str_replace("\0", '?', $argument);
        }
        if (!preg_match('/[()%!^"<>&|\s[\]=;*?\'$]/', $argument)) {
            return $argument;
        }
        $argument = preg_replace('/(\\\\+)$/', '$1$1', $argument);

        return '"'.str_replace(['"', '^', '%', '!', "\n"], ['""', '"^^"', '"^%"', '"^!"', '!LF!'], $argument).'"';
    }

    /**
     * @param EnvArray $env
     */
    private function replacePlaceholders(string $commandline, array $env): string
    {
        return preg_replace_callback('/"\$\{:([_a-zA-Z]++[_a-zA-Z0-9]*+)\}"/', function ($matches) use ($commandline, $env) {
            if (!isset($env[$matches[1]]) || false === $env[$matches[1]]) {
                throw new InvalidArgumentException(\sprintf('Command line is missing a value for parameter "%s": ', $matches[1]).$commandline);
            }

            return $this->escapeArgument($env[$matches[1]]);
        }, $commandline);
    }

    /**
     * @return EnvArray
     */
    private function getDefaultEnv(): array
    {
        $env = getenv();
        $env = ('\\' === \DIRECTORY_SEPARATOR ? array_intersect_ukey($env, $_SERVER, 'strcasecmp') : array_intersect_key($env, $_SERVER)) ?: $env;
        $env = $_ENV + ('\\' === \DIRECTORY_SEPARATOR ? array_diff_ukey($env, $_ENV, 'strcasecmp') : $env);

        if (\in_array(\PHP_SAPI, ['cli', 'phpdbg', 'embed'], true)) {
            return $env;
        }

View on GitHub (pinned to 99b85026db)