Landscape wallpaper rejected on iOS/iPadOS kiosk devices: workaround and limitations

iOS

When uploading a landscape-oriented wallpaper image to an iOS or iPadOS Blueprint, the Esper Console rejects the file with the error: The image is [width] pixel wide. It's supposed to be less than or equal to height.

Why this happens

The Esper Console enforces a validation rule requiring wallpaper images to be taller than they are wide (portrait or square orientation). This rule applies to all iOS and iPadOS Blueprints regardless of the physical orientation the device is locked to. Because the validation is enforced at upload time, landscape images cannot be submitted directly — even for devices that will only ever display in landscape mode.

Steps

1. Using an image editor, rotate your landscape wallpaper image 90° so that the height is greater than the width. Save the rotated file. Note that on landscape-locked iPads, iOS will re-rotate or crop this image when applying it to the screen — the final result may appear distorted or misaligned, and this cannot be corrected from within Esper.
2. In the Esper Console, navigate to Blueprints → [Blueprint Name] → Appearance → Wallpaper.
3. Upload the rotated portrait image to the Home Screen field.
4. Upload the same rotated portrait image to the Lock Screen field. Using the same image in both fields prevents a mismatch between the two screens after iOS re-rotates the image on the device.
5. Select Save.
6. Navigate to Blueprints → [Blueprint Name] → Converge, select the target devices, and select Apply.
7. After convergence completes, inspect each device screen to confirm how iOS has rendered the wallpaper.

Verify: The blueprint status shows In Sync in Devices & Groups within 10 minutes of applying. Open the device home screen and lock screen to confirm a wallpaper is displayed. If the image appears distorted or cropped, this is expected behavior caused by iOS re-rotating a portrait image on a landscape-locked device — it is not a bug in Esper.

If this doesn't resolve it

If the rendered wallpaper is unacceptable for your deployment, or if the device does not reflect the new wallpaper after the blueprint shows In Sync, contact Esper Support with the following information:

• The Blueprint name and UUID
• Device model and iPadOS version
• A screenshot of the wallpaper result on the device
• The original image dimensions (width × height in pixels)

Still need help?

If the steps above don't resolve the issue, submit a support ticket with your device model, Android version, Esper Agent version, and a description of what you've already tried — this helps the support team investigate without a follow-up.