symfony/process · error · RuntimeException

Setting options while the process is running is not…

Error message

Setting options while the process is running is not possible.

What it means

setOptions() throws this RuntimeException when called while the process is running. Options such as blocking_pipes, create_process_group, and create_new_console are applied by the OS when the process is spawned, so they are immutable once started.

Solutions

Call setOptions() before start()/run().
Guard with if (!$process->isRunning()) or stop the process before changing options.
Recreate the Process with the desired options and start it again.

Example fix

// before
$process->start();
$process->setOptions(['create_new_console' => true]); // RuntimeException

// after
$process->setOptions(['create_new_console' => true]);
$process->start();

Defensive patterns

Strategy: validation

Validate before calling

if (!$process->isRunning()) {
    $process->setOptions(['create_new_console' => true]);
}

Try / catch

try {
    $process->setOptions($options);
} catch (\RuntimeException $e) {
    // running: recreate the process with the new options
}

Prevention

Set all options (blocking_pipes, create_process_group, create_new_console) before start().
Keep an immutable pre-start configuration phase; don't mutate Process objects after start().
Only use keys from the documented list (blocking_pipes, create_process_group, create_new_console).

When it happens

Trigger: Calling setOptions([...]) after start()/run() on a still-running process; seen in tests like testOptionCreateNewConsole and testItReturnsFastAfterStart when mutating options late.

Common situations: Enabling create_new_console so a subprocess survives the parent exit — but applying it after start; centralized config code adjusting process options in response to runtime events.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

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

Appendix: source

Thrown at Process.php:1255

        if (!$this->isStarted()) {
            throw new LogicException('Start time is only available after process start.');
        }

        return $this->starttime;
    }

    /**
     * Defines options to pass to the underlying proc_open().
     *
     * @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

View on GitHub (pinned to 99b85026db)