symfony/process · error · RuntimeException

Setting ignored signals while the process is running is not…

Error message

Setting ignored signals while the process is running is not possible.

What it means

setIgnoredSignals() stores signals to ignore for the process, but this configuration can only happen before the process starts. Once isRunning() is true the OS process already exists and signal dispositions cannot be applied, so a RuntimeException is thrown.

Solutions

Call setIgnoredSignals() before start() or run()
Check $process->isRunning() before calling and defer the change to a fresh process
Stop the process, change signals, restart

Example fix

// before
$process->start();
$process->setIgnoredSignals([SIGTERM]);
// after
$process->setIgnoredSignals([SIGTERM]);
$process->start();

Defensive patterns

Strategy: validation

Validate before calling

if (!$process->isRunning()) {
    $process->setIgnoredSignals([SIGTERM]);
}

Try / catch

try { $process->setIgnoredSignals($signals); } catch (RuntimeException $e) { /* process already running; defer to restart */ }

Prevention

Configure all process settings (env, timeout, signals, options) before start()
Centralize process setup in one factory function
Assert !isRunning() in debug builds before configuration calls

When it happens

Trigger: Calling $process->setIgnoredSignals([SIGTERM]) after start()/run() while the child process is still alive.

Common situations: Trying to reconfigure ignored signals mid-run in long-lived workers, calling setIgnoredSignals from a callback or after wait() hasn't yet returned but process still runs.

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/da99017a80ed580b. Report an issue: GitHub.

Appendix: source

Thrown at Process.php:1278

        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;
    }

    /**
     * Returns whether TTY is supported on the current operating system.
     */
    public static function isTtySupported(): bool
    {
        static $isTtySupported;

        return $isTtySupported ??= ('/' === \DIRECTORY_SEPARATOR && stream_isatty(\STDOUT) && @is_writable('/dev/tty'));
    }

    /**
     * Returns whether PTY is supported on the current operating system.
     */

View on GitHub (pinned to 99b85026db)