How to Fix imagegrabwindow Errors on WAMP Server

imagegrabwindow() fails on WAMP for four common reasons: the request is not running on Windows, GD or the function is unavailable in the active PHP runtime, the site uses a different PHP configuration than expected, or the supplied HWND is invalid. Check those in that order.

The function is documented as Windows-only. It accepts a Windows HWND and an optional Boolean client_area argument, returns an image on success, and returns false on failure. PHP documents an E_NOTICE for an invalid handle and an E_WARNING when the Windows API is too old. See the PHP imagegrabwindow() manual.

1. Identify the exact failure

Use the message and return value to select the right fix:

What you see	Likely cause	Where to investigate
`Call to undefined function imagegrabwindow()`	Non-Windows request, GD not loaded, or a different PHP runtime	Operating system, PHP version, `function_exists()`, and GD
Notice about an invalid handle	The HWND is missing, stale, or belongs to another window	Window creation and the value passed as the first argument
`imagegrabwindow()` returns `false`	Capture failed after the call was available	HWND validity and Windows API warnings
Warning about an old Windows API	The Windows API does not meet PHP’s requirement	Windows version and PHP compatibility

2. Confirm the runtime used by the failing web request

Do not rely on the PHP shown by php -v in a terminal. WampServer can select PHP versions per VirtualHost in FastCGI mode, so the browser request may use another version or configuration. Create a temporary file in the affected site’s document root:

<?php
var_dump(PHP_OS_FAMILY);
var_dump(PHP_VERSION);
var_dump(function_exists('imagegrabwindow'));
var_dump(extension_loaded('gd'));

Open that file through the same hostname and VirtualHost that produces the error. PHP_OS_FAMILY must be "Windows". function_exists() must be true, and GD must be loaded. The function_exists() documentation explains the availability check. Remove this diagnostic file after use.

If the request is not running on Windows

Changing WAMP’s GD setting cannot add a Windows-only function to a Linux, macOS, container, or remote PHP runtime. Run the capture in a Windows PHP process, or use a browser-based screenshot service. If the goal is a full desktop image rather than one application window, PHP’s imagegrabscreen() is also Windows-only; it does not solve a non-Windows runtime.

3. Enable the correct GD extension

If the request is on Windows but GD or imagegrabwindow() is unavailable, inspect the php.ini used by that web request. On Windows, PHP enables GD through its extension DLL:

PHP 8.0 and later: php_gd.dll
PHP versions before 8.0: php_gd2.dll

Use WampServer’s PHP/version controls to select the intended PHP release and enable GD. Do not paste an old extension=php_gd2.dll line into a current PHP 8 setup without checking the installed DLL name. The PHP GD installation documentation describes the extension configuration.

Open the PHP configuration associated with the failing site, not only the CLI configuration.
Verify that the GD extension line references the DLL present in that PHP installation.
Save the configuration.
Reload the active Apache/PHP service from WampServer.
Request the diagnostic file again and confirm both function_exists('imagegrabwindow') and extension_loaded('gd') are true.

4. Use PHP 8-compatible calling code

PHP 8 changed a successful result from a resource to a GdImage instance and changed client_area to expect a Boolean. Older examples may pass an integer or describe the result as a resource. Use true or false explicitly and always check the return value before writing the image:

<?php

$handle = /* a valid Windows HWND */;
$image = imagegrabwindow($handle, false);

if ($image === false) {
    throw new RuntimeException(
        'Window capture failed; check the HWND and any Windows API warning.'
    );
}

imagepng($image, __DIR__ . '/capture.png');
imagedestroy($image);

Set client_area to true when you want the application’s client area, or false when you want the complete window capture according to the behavior of your PHP/Windows combination. The important compatibility point is that the argument is a Boolean on PHP 8 and later.

5. Validate the HWND

The first argument is not a process ID, window title, browser URL, or screen coordinate. It is the numeric Windows HWND for the target window. The PHP manual’s example obtains it from a COM object’s HWND property.

<?php

$browser = new COM('InternetExplorer.Application');
$browser->Visible = true;
$browser->Navigate('https://example.com');

while ($browser->Busy) {
    com_message_pump(100);
}

$handle = (int) $browser->HWND;
if ($handle <= 0) {
    throw new RuntimeException('The browser did not provide a valid HWND.');
}

$image = imagegrabwindow($handle, false);
if ($image === false) {
    throw new RuntimeException('imagegrabwindow() could not capture the HWND.');
}

imagepng($image, __DIR__ . '/browser.png');
imagedestroy($image);
$browser->Quit();

Keep the target application alive until the capture finishes. A handle can become invalid when the window has not opened yet, has already closed, or has been replaced. If the application creates a new top-level window during navigation, obtain the current HWND again instead of reusing an earlier value.

HWND checklist

Confirm the value is numeric and greater than zero.
Obtain it after the target window is created.
Capture before closing or reusing the application object.
Do not confuse a child control handle with the top-level window handle expected by your capture.
Run the web server under a Windows desktop session that can access the interactive window. A service or unattended session may not have a visible desktop window to capture.

6. Distinguish a window capture from a screen capture

imagegrabwindow() captures one window identified by an HWND. For the entire desktop, PHP documents imagegrabscreen():

<?php

$image = imagegrabscreen();
if ($image === false) {
    throw new RuntimeException('The screen capture failed.');
}

imagepng($image, __DIR__ . '/screen.png');
imagedestroy($image);

Both functions are Windows-only. Selecting imagegrabscreen() will not fix an application running under Linux, macOS, or a non-Windows container. See the imagegrabscreen() manual.

7. A repeatable troubleshooting procedure

Capture the exact error. Enable your normal PHP error logging and record whether the message is an undefined function, invalid handle notice, API warning, or a plain false result.
Test from the failing URL. Check PHP_OS_FAMILY, PHP_VERSION, function_exists(), and extension_loaded('gd') in that request.
Correct the environment. Select a Windows PHP runtime and the correct GD DLL for that PHP version, then reload WampServer.
Test with a known live window. Create the target window, wait until it exists, read its current HWND, and keep it open through capture.
Guard the return value. Never pass false to imagepng(), imagejpeg(), or another image writer.
Remove temporary diagnostics. Runtime-information pages can expose configuration details and should not remain publicly accessible.

8. Common errors and fixes

“Call to undefined function imagegrabwindow()”

Cause: The request is not on Windows, GD is disabled, or the VirtualHost uses a different PHP installation. Fix: Run the diagnostic script through the affected site, verify the OS family, enable the correct GD DLL, reload the service, and retest.

“Invalid window handle” notice

Cause: The HWND is zero, stale, belongs to a closed window, or was obtained before the application created its top-level window. Fix: obtain the handle after creation, validate it, keep the application alive, and capture immediately.

The call returns `false` without a useful image error

Cause: The capture operation failed even though the function exists. Fix: check the HWND and PHP error log, verify the Windows API requirement, and ensure the web-server process has access to the interactive desktop.

An old tutorial says to enable `php_gd2.dll`

Cause: The tutorial targets PHP before 8.0. Fix: inspect the PHP version used by the request. PHP 8 and later use php_gd.dll; do not copy the old filename blindly.

The CLI test works, but the website fails

Cause: CLI PHP and the WampServer VirtualHost can use different versions or php.ini files. Fix: trust the request-level diagnostic output from the failing hostname and adjust that site’s FastCGI/PHP selection.

9. Reliability, performance, and deployment notes

Window state matters: a minimized, hidden, closed, or not-yet-created window may not produce the capture you expect. Define when the application is ready before reading its HWND.
Use bounded waits: waiting forever for a browser or desktop application can leave PHP workers occupied. Add an application-level timeout and log the stage that timed out.
Protect the endpoint: do not expose arbitrary HWND capture or COM automation to unauthenticated users. Restrict the script to trusted callers.
Clean up resources: call imagedestroy() after writing the image and close the automated application when finished.
Size affects memory: large window captures create large GD images. Save or stream the result promptly and avoid retaining multiple captures in one request.
Desktop automation is stateful: concurrent requests can target the wrong window if they share one browser or desktop session. Use isolated processes or serialize access.
Check the actual output: a successful GD object only proves that an image was returned; it does not prove that the intended window contents were visible.

Or skip the browser setup

If you need a webpage screenshot rather than a Windows desktop window, ScreenshotNeo provides a website screenshot API and MCP server. It accepts one GET request and returns PNG, JPEG, WebP, or PDF, so there is no WAMP desktop session or HWND to manage.

See the ScreenshotNeo API documentation for the request options.

cURL

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

Python

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
r.raise_for_status()
open("shot.webp", "wb").write(r.content)

Node.js

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot failed: ${res.status}`);
const body = Buffer.from(await res.arrayBuffer());
require('fs').writeFileSync('shot.webp', body);

ScreenshotNeo removes cookie and consent banners, newsletter popups, and chat widgets before capture; bot checks, blank pages, failed loads, timeouts, and cache hits are not billed. Each response reports the result through X-Page-Verdict and X-Billed headers. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. The Free plan includes 1,000 screenshots per month with no card, and paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account.

FAQ

Is imagegrabwindow() available on Linux?

No. PHP documents it as Windows-only. Use a Windows runtime or a web screenshot service for a webpage.

Does enabling GD repair an invalid HWND?

No. GD makes the function available when configured correctly; an invalid or stale HWND still causes a notice or failed capture.

Should client_area be 0 or false?

Use a Boolean, especially on PHP 8 and later: true or false.

Why does the return type differ between tutorials?

PHP 8 changed successful results from a resource to a GdImage object. Check the PHP version serving the request.

What should I use for a full desktop screenshot?

Use imagegrabscreen(), remembering that it is also Windows-only.