Title: WP_REST_Attachments_Controller::validate_image_dimensions
Published: August 20, 2026

---

# WP_REST_Attachments_Controller::validate_image_dimensions( int $width, int $height, string $image_size, int $attachment_id ): true|󠀁[WP_Error](https://developer.wordpress.org/reference/classes/wp_error/)󠁿

## In this article

 * [Parameters](https://developer.wordpress.org/reference/classes/wp_rest_attachments_controller/validate_image_dimensions/?output_format=md#parameters)
 * [Return](https://developer.wordpress.org/reference/classes/wp_rest_attachments_controller/validate_image_dimensions/?output_format=md#return)
 * [Source](https://developer.wordpress.org/reference/classes/wp_rest_attachments_controller/validate_image_dimensions/?output_format=md#source)
 * [Related](https://developer.wordpress.org/reference/classes/wp_rest_attachments_controller/validate_image_dimensions/?output_format=md#related)
 * [Changelog](https://developer.wordpress.org/reference/classes/wp_rest_attachments_controller/validate_image_dimensions/?output_format=md#changelog)

[ Back to top](https://developer.wordpress.org/reference/classes/wp_rest_attachments_controller/validate_image_dimensions/?output_format=md#wp--skip-link--target)

This function’s access is marked private. This means it is not intended for use 
by plugin or theme developers, only by core. It is listed here for completeness.

Validates that uploaded image dimensions are appropriate for the specified image
size.

## 󠀁[Parameters](https://developer.wordpress.org/reference/classes/wp_rest_attachments_controller/validate_image_dimensions/?output_format=md#parameters)󠁿

 `$width`intrequired

Uploaded image width.

`$height`intrequired

Uploaded image height.

`$image_size`stringrequired

The target image size name.

`$attachment_id`intrequired

The attachment ID.

## 󠀁[Return](https://developer.wordpress.org/reference/classes/wp_rest_attachments_controller/validate_image_dimensions/?output_format=md#return)󠁿

 true|[WP_Error](https://developer.wordpress.org/reference/classes/wp_error/) True
if valid, [WP_Error](https://developer.wordpress.org/reference/classes/wp_error/)
if invalid.

## 󠀁[Source](https://developer.wordpress.org/reference/classes/wp_rest_attachments_controller/validate_image_dimensions/?output_format=md#source)󠁿

    ```php
    private function validate_image_dimensions( int $width, int $height, string $image_size, int $attachment_id ) {
    	// All image sizes require positive dimensions.
    	if ( $width <= 0 || $height <= 0 ) {
    		return new WP_Error(
    			'rest_upload_invalid_dimensions',
    			__( 'Uploaded image must have positive dimensions.' ),
    			array( 'status' => 400 )
    		);
    	}

    	/*
    	 * 'original' size: the full-size image that replaces the main file (see
    	 * sideload_item()/finalize_item()). The endpoint expects any EXIF
    	 * orientation to be applied to the image already, which can swap width
    	 * and height, so the dimensions must match the stored dimensions or be
    	 * their transpose.
    	 */
    	if ( 'original' === $image_size ) {
    		$metadata = wp_get_attachment_metadata( $attachment_id, true );
    		if ( is_array( $metadata ) && isset( $metadata['width'], $metadata['height'] ) ) {
    			$expected_width  = (int) $metadata['width'];
    			$expected_height = (int) $metadata['height'];

    			$matches_dimensions    = $width === $expected_width && $height === $expected_height;
    			$transposes_dimensions = $width === $expected_height && $height === $expected_width;

    			if ( ! $matches_dimensions && ! $transposes_dimensions ) {
    				return new WP_Error(
    					'rest_upload_dimension_mismatch',
    					sprintf(
    						/* translators: 1: Actual width, 2: actual height, 3: expected width, 4: expected height. */
    						__( 'Uploaded image dimensions (%1$dx%2$d) do not match original image dimensions (%3$dx%4$d).' ),
    						$width,
    						$height,
    						$expected_width,
    						$expected_height
    					),
    					array( 'status' => 400 )
    				);
    			}
    		}
    		return true;
    	}

    	// 'full' size (PDF thumbnails) and 'scaled': no further constraints.
    	if ( in_array( $image_size, array( 'full', 'scaled' ), true ) ) {
    		return true;
    	}

    	/*
    	 * 'animated_video_poster' companion: a static poster image for the
    	 * converted video. It is a real image (so it has positive dimensions)
    	 * but is not a registered sub-size, so it has no dimension constraint.
    	 */
    	if ( 'animated_video_poster' === $image_size ) {
    		return true;
    	}

    	// Regular image sizes: validate against registered size constraints.
    	$registered_sizes = wp_get_registered_image_subsizes();

    	if ( ! isset( $registered_sizes[ $image_size ] ) ) {
    		return new WP_Error(
    			'rest_upload_unknown_size',
    			__( 'Unknown image size.' ),
    			array( 'status' => 400 )
    		);
    	}

    	$size_data  = $registered_sizes[ $image_size ];
    	$max_width  = (int) $size_data['width'];
    	$max_height = (int) $size_data['height'];

    	// Validate dimensions don't exceed the registered size maximums.
    	// Allow 1px tolerance for rounding differences.
    	$tolerance = 1;

    	if ( $this->dimension_exceeds_max( $width, $max_width, $tolerance ) ) {
    		return new WP_Error(
    			'rest_upload_dimension_mismatch',
    			sprintf(
    				/* translators: 1: Image size name, 2: maximum width, 3: actual width. */
    				__( 'Uploaded image width (%3$d) exceeds maximum for "%1$s" size (%2$d).' ),
    				$image_size,
    				$max_width,
    				$width
    			),
    			array( 'status' => 400 )
    		);
    	}

    	if ( $this->dimension_exceeds_max( $height, $max_height, $tolerance ) ) {
    		return new WP_Error(
    			'rest_upload_dimension_mismatch',
    			sprintf(
    				/* translators: 1: Image size name, 2: maximum height, 3: actual height. */
    				__( 'Uploaded image height (%3$d) exceeds maximum for "%1$s" size (%2$d).' ),
    				$image_size,
    				$max_height,
    				$height
    			),
    			array( 'status' => 400 )
    		);
    	}

    	return true;
    }
    ```

[View all references](https://developer.wordpress.org/reference/files/wp-includes/rest-api/endpoints/class-wp-rest-attachments-controller.php/)
[View on Trac](https://core.trac.wordpress.org/browser/tags/7.1/src/wp-includes/rest-api/endpoints/class-wp-rest-attachments-controller.php#L2620)
[View on GitHub](https://github.com/WordPress/wordpress-develop/blob/7.1/src/wp-includes/rest-api/endpoints/class-wp-rest-attachments-controller.php#L2620-L2726)

## 󠀁[Related](https://developer.wordpress.org/reference/classes/wp_rest_attachments_controller/validate_image_dimensions/?output_format=md#related)󠁿

| Uses | Description | 
| [WP_REST_Attachments_Controller::dimension_exceeds_max()](https://developer.wordpress.org/reference/classes/wp_rest_attachments_controller/dimension_exceeds_max/)`wp-includes/rest-api/endpoints/class-wp-rest-attachments-controller.php` |

Checks whether a dimension exceeds the maximum allowed value.

  | 
| [wp_get_registered_image_subsizes()](https://developer.wordpress.org/reference/functions/wp_get_registered_image_subsizes/)`wp-includes/media.php` |

Returns a normalized list of all currently registered image sub-sizes.

  | 
| [wp_get_attachment_metadata()](https://developer.wordpress.org/reference/functions/wp_get_attachment_metadata/)`wp-includes/post.php` |

Retrieves attachment metadata for attachment ID.

  | 
| [__()](https://developer.wordpress.org/reference/functions/__/)`wp-includes/l10n.php` |

Retrieves the translation of $text.

  | 
| [WP_Error::__construct()](https://developer.wordpress.org/reference/classes/wp_error/__construct/)`wp-includes/class-wp-error.php` |

Initializes the error.

  |

[Show 2 more](https://developer.wordpress.org/reference/classes/wp_rest_attachments_controller/validate_image_dimensions/?output_format=md#)
[Show less](https://developer.wordpress.org/reference/classes/wp_rest_attachments_controller/validate_image_dimensions/?output_format=md#)

| Used by | Description | 
| [WP_REST_Attachments_Controller::sideload_item()](https://developer.wordpress.org/reference/classes/wp_rest_attachments_controller/sideload_item/)`wp-includes/rest-api/endpoints/class-wp-rest-attachments-controller.php` |

Side-loads a media file without creating a new attachment.

  |

## 󠀁[Changelog](https://developer.wordpress.org/reference/classes/wp_rest_attachments_controller/validate_image_dimensions/?output_format=md#changelog)󠁿

| Version | Description | 
| [7.1.0](https://developer.wordpress.org/reference/since/7.1.0/) | Introduced. |

## User Contributed Notes

You must [log in](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Fclasses%2Fwp_rest_attachments_controller%2Fvalidate_image_dimensions%2F)
before being able to contribute a note or feedback.