What causes "Failed to build stream" in Intervention/image?

Free memory / raise memory_limit before the operation.

Intervention/image · error · Intervention\Image\Exceptions\StreamException

Failed to build stream

Error message

Failed to build stream

What it means

After buildStreamOrFail() picks a construction strategy, a final check verifies the returned handle is not false; if it is, this generic StreamException is thrown. In practice the only strategy that can return false here (rather than throw its own specific exception) is the null branch whose fopen('php://temp', 'r+') failed. Like error 464 it signals an environment failure to create a stream, just via the shared post-check.

Source

Thrown at src/Traits/CanBuildStream.php:43

            is_string($data) => function (mixed $data) {
                $stream = fopen('php://temp', 'r+');

                if ($stream === false) {
                    throw new StreamException('Failed to build stream from string');
                }

                fwrite($stream, $data);
                return $stream;
            },
            default => throw new InvalidArgumentException(
                'Unable to create stream from ' . gettype($data) . '. Use only null, string or resource.',
            ),
        };

        $stream = $buildStrategy($data);

        if ($stream === false) {
            throw new StreamException('Failed to build stream');
        }

        $rewind = rewind($stream);

        if ($rewind === false) {
            throw new StreamException('Failed to rewind stream');
        }

        return $stream;
    }
}

View on GitHub (pinned to 5598b9e397)

Solutions

Free memory / raise memory_limit before the operation.
Verify the temp filesystem is writable and has space: check sys_temp_dir and tmpfs mounts; clear or remount /tmp.
Catch Intervention\Image\Exceptions\StreamException at the call site and surface an environment-level error message.
If reproducible, test fopen('php://temp', 'r+') in isolation to confirm the PHP runtime itself is broken, then fix the runtime/container config.

Example fix

// before
// /tmp full -> fopen('php://temp') fails
$file = \Intervention\Image\File::create(); // StreamException: Failed to build stream

// after
// free temp space / raise memory_limit first, then
$file = \Intervention\Image\File::create();

Defensive patterns

Strategy: try-catch

Validate before calling

// sanity-check the temp stream factory before heavy work
if (fopen('php://temp', 'r+') === false) {
    throw new \RuntimeException('php://temp unavailable - check memory_limit and tmp dir');
}

Try / catch

try {
    $file = \Intervention\Image\File::create();
} catch (\Intervention\Image\Exceptions\StreamException $e) {
    // environment issue: surface it, do not retry blindly
    throw new \RuntimeException('Cannot create temp stream: ' . $e->getMessage());
}

Prevention

Keep memory_limit and temp disk space healthy in image-processing environments.
Add health checks that verify fopen('php://temp', 'r+') works in containers/sandboxes.
Treat StreamException from stream construction as infrastructure failure, not input failure.

When it happens

Trigger: Calling buildStreamOrFail(null) — directly or through APIs that default to null, such as File/decoder paths that construct an empty working stream — while php://temp cannot be opened. Correlates with memory_limit exhaustion, a full or unwritable system temp directory, or a sandbox (e.g. seccomp/open_basedir hardening) blocking temp stream creation.

Common situations: Hardened shared hosting or containers where /tmp is mounted read-only or size-limited; PHP-FPM workers already at memory_limit; systemd PrivateTmp with a full tmpfs; rare stream wrappers disabled via disable_functions-like hardening.

Related errors

AI-assisted analysis of Intervention/image@5598b9e397 (2026-08-23). Data as JSON: /api/errors/6d0ebf2b1e2c4511. Report an issue: GitHub.