symfony/process · error · InvalidArgumentException

Expected a process that failed during startup, but the…

Error message

Expected a process that failed during startup, but the given process was started successfully.

What it means

Guard in ProcessStartFailedException::__construct: this exception is meant for processes that never started. If the given Process was already started successfully, the caller has the wrong exception type and an InvalidArgumentException is thrown instead.

Solutions

1. Only construct ProcessStartFailedException when $process->isStarted() is false
2. Use ProcessFailedException for processes that started but later failed
3. Inspect the Process state before choosing which Process exception to throw

When it happens

Trigger: Thrown at Exception/ProcessStartFailedException.php:26 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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

Appendix: source

Thrown at Exception/ProcessStartFailedException.php:26

 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

namespace Symfony\Component\Process\Exception;

use Symfony\Component\Process\Process;

/**
 * Exception for processes failed during startup.
 */
class ProcessStartFailedException extends ProcessFailedException
{
    public function __construct(
        private Process $process,
        ?string $message,
    ) {
        if ($process->isStarted()) {
            throw new InvalidArgumentException('Expected a process that failed during startup, but the given process was started successfully.');
        }

        $error = \sprintf('The command "%s" failed.'."\n\nWorking directory: %s\n\nError: %s",
            $process->getCommandLine(),
            $process->getWorkingDirectory(),
            $message ?? 'unknown'
        );

        // Skip parent constructor
        RuntimeException::__construct($error);
    }

    public function getProcess(): Process
    {
        return $this->process;
    }
}

View on GitHub (pinned to 99b85026db)