symfony/process · error · LogicException

Invalid option " " passed to " ()". Supported options are "…

Error message

Invalid option "%s" passed to "%s()". Supported options are "%s".

What it means

Symfony Process throws this LogicException when an unsupported option key is passed to setOptions(). Only 'blocking_pipes', 'create_process_group' and 'create_new_console' are recognized; any other key restores the previous options and throws immediately so typos fail fast.

Solutions

1. Use only supported keys: blocking_pipes, create_process_group, create_new_console
2. Check the exact spelling against the $existingOptions array in Process.php
3. Move non-option settings to their dedicated setters (setTimeout, setEnv, etc.)

Example fix

// before
$process->setOptions(['timeout' => 30]);
// after
$process->setTimeout(30);
$process->setOptions(['create_new_console' => true]);

$allowed = ['blocking_pipes','create_process_group','create_new_console'];
$invalid = array_diff(array_keys($options), $allowed);
if ($invalid) { throw new InvalidArgumentException('Unknown options: '.implode(',', $invalid)); }
$process->setOptions($options);

try { $process->setOptions($opts); } catch (LogicException $e) { /* fix option keys */ }

When it happens

Trigger: Calling $process->setOptions([...]) with a key not in ['blocking_pipes','create_process_group','create_new_console'], e.g. 'timeout', 'env', or a misspelled option like 'create_new_consoles'.

Common situations: Copy-pasting options from another library (symfony/process options vs proc_open flags), typos in option names, upgrading Symfony where option names changed, confusion between constructor options and runtime setters.

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

• 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.
• Unable to kill the process

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

Appendix: source

Thrown at Process.php:1264

     *
     * @see https://php.net/proc_open for the options supported by PHP.
     *
     * Enabling the "create_new_console" option allows a subprocess to continue
     * to run after the main process exited, on both Windows and *nix
     */
    public function setOptions(array $options): void
    {
        if ($this->isRunning()) {
            throw new RuntimeException('Setting options while the process is running is not possible.');
        }

        $defaultOptions = $this->options;
        $existingOptions = ['blocking_pipes', 'create_process_group', 'create_new_console'];

        foreach ($options as $key => $value) {
            if (!\in_array($key, $existingOptions)) {
                $this->options = $defaultOptions;
                throw new LogicException(\sprintf('Invalid option "%s" passed to "%s()". Supported options are "%s".', $key, __METHOD__, implode('", "', $existingOptions)));
            }
            $this->options[$key] = $value;
        }
    }

    /**
     * Defines a list of posix signals that will not be propagated to the process.
     *
     * @param list<\SIG*> $signals
     */
    public function setIgnoredSignals(array $signals): void
    {
        if ($this->isRunning()) {
            throw new RuntimeException('Setting ignored signals while the process is running is not possible.');
        }

        $this->ignoredSignals = $signals;
    }

View on GitHub (pinned to 99b85026db)