Troubleshooting

Solutions for common ImageMagick errors and unexpected output.

Run these first (diagnostics)

Run a few commands before you dig into a specific error; they show version, delegates, policies, and what ImageMagick thinks about your file.

Linux / macOS (bash)

# Version + built-in delegates (formats this binary can handle)
magick --version

# One format, with read/write flags
magick -list format | grep -i webp

# Memory / disk / thread limits
magick -list resource

# Which policy.xml files are loaded and coder rules
magick -list policy

# One file decoded as ImageMagick sees it
magick identify -verbose path/to/your.jpg

# True container type from bytes (optional)
file path/to/your.jpg

Windows (PowerShell)

magick --version

magick -list format | Select-String -Pattern webp -CaseSensitive:$false

magick -list resource

magick -list policy

magick identify -verbose path\to\your.jpg

There is no built-in file command; magick identify already reports the detected format.

Fix error messages

unable to open image … No such file or directory

Error:

magick: unable to open image 'input.jpg': No such file or directory

Cause: ImageMagick cannot read the path you passed: wrong working directory, a typo, or a path that contains spaces without quoting.

Fix:

• Print where you are: pwd (Linux/macOS) or Get-Location (PowerShell). Paths like input.jpg are relative to that directory.
• Prefer explicit paths: magick ./photos/input.jpg … or magick "C:\Users\you\Pictures\My Photo.jpg" … (quotes when the path or filename has spaces).
• On Windows, check drive letters and backslashes; inside WSL, /mnt/c/... is not the same path as C:\... from Windows Explorer.

magick: not found / 'magick' is not recognized

Cause: ImageMagick 7 is not installed, or the magick binary is not on your system PATH.

Fix: Verify which version you have:

magick --version
convert --version

If convert works but magick does not, you have ImageMagick 6 installed. In version 6, the commands are standalone binaries (convert, identify, mogrify). In version 7, they are subcommands of magick (magick convert, magick identify, or just magick directly).

To get version 7, see Install ImageMagick.

If neither command works, ImageMagick is not installed or is not on your PATH. On Linux, check with which magick or which convert. On Windows, verify that the ImageMagick install directory is listed in your system PATH environment variable.

no decode delegate for this image format

Error:

magick: no decode delegate for this image format 'HEIC'

Cause: Your ImageMagick build does not include support for the requested format. Each format requires a delegate library (e.g., libheif for HEIC, libwebp for WebP).

Fix: Check which formats your build supports:

Linux / macOS

magick -list format | grep -i heic

Windows (PowerShell)

magick -list format | Select-String -Pattern heic -CaseSensitive:$false

If the format is missing, you need to install the delegate library and either reinstall ImageMagick or rebuild from source. On macOS with Homebrew, brew reinstall imagemagick usually picks up newly installed libraries. On Linux, install the delegate package (e.g., libheif-dev) and rebuild.

Formats marked r-- support reading only. Formats marked rw- support reading and writing.

no encode delegate for this image format

Error:

magick: no encode delegate for this image format 'HEIC'

Cause: Your build can read the format but cannot write to it. HEIC is a common example: many builds include read support via libheif but not write support.

Fix: Check the format’s read/write support:

Linux / macOS

magick -list format | grep -i heic

Windows (PowerShell)

magick -list format | Select-String -Pattern heic -CaseSensitive:$false

A line showing r-- means read-only. You need a build with write support (rw- or rw+), or convert to a different output format.

cache resources exhausted

Error:

magick: cache resources exhausted 'image.jpg'

Cause: The image exceeds ImageMagick’s memory, disk, or dimension limits. This happens with very large images or when processing many images in sequence.

Fix: Check your current limits:

magick -list resource

Increase limits for the current command using -limit:

magick -limit memory 2GiB -limit disk 4GiB input.jpg -resize 800x600 output.jpg

To change defaults permanently, edit the policy.xml file (or the policy fragment your packager uses). Find active policy paths with:

Linux / macOS

magick -list policy | head -25

Windows (PowerShell)

magick -list policy | Select-Object -First 25

ImageMagick may load several policy files (system, user, delegates). Paths differ between the Windows installer, Homebrew, Debian packages, and Docker images; use the output above on your machine.

Update the resource values:

<policy domain="resource" name="memory" value="2GiB"/>
<policy domain="resource" name="disk" value="4GiB"/>

not authorized

Error:

magick: not authorized 'input.pdf'

Cause: A policy.xml rule blocks that coder (PDF, EPS, PS, SVG, etc.). Those formats often invoke Ghostscript or other delegates that have had serious security issues.

Do not relax policy for untrusted files. Changing rights="none" to read|write lets ImageMagick decode vectors and PostScript that can be malicious. Only do this on machines that never process uploads or downloads you do not fully trust, and keep ImageMagick and Ghostscript patched.

Fix (step 1): See which policy files ImageMagick actually loaded (paths differ by OS and packager):

Linux / macOS

magick -list policy | head -40

Windows (PowerShell)

magick -list policy | Select-Object -First 40

Fix (step 2): Open the file that contains the <policy domain="coder" … pattern="PDF" /> line (often named policy.xml). Typical locations (always confirm with the output above):

Install	Where to look
Homebrew (macOS)	$(brew --prefix)/etc/ImageMagick-7/ (Apple Silicon: often /opt/homebrew/etc/ImageMagick-7/; Intel: often /usr/local/etc/ImageMagick-7/). Run brew --prefix imagemagick if unsure.
Ubuntu / Debian (apt)	/etc/ImageMagick-7/policy.xml or /etc/ImageMagick-6/policy.xml (depends on package). sudo find /etc -name policy.xml 2>/dev/null lists candidates.
Windows installer	Under the ImageMagick program folder, e.g. C:\Program Files\ImageMagick-7.1.2-Q16-HDRI\policy.xml (folder name matches your version).

Fix (step 3): Find the restrictive line and change rights only if you accept the risk above:

<policy domain="coder" rights="none" pattern="PDF" />

to:

<policy domain="coder" rights="read|write" pattern="PDF" />

Save the file, then run magick -list policy again to confirm the rule changed. Some installs ship multiple fragments; edit the one that still shows none for your coder.

insufficient image data / improper image header

Error:

magick: insufficient image data in file 'input.jpg'
magick: improper image header 'photo.bmp'

Cause: The file is corrupted, truncated (incomplete download), or has the wrong file extension. A file named .jpg that contains PNG data, or a file that was only partially downloaded, triggers this error.

Fix: Verify the file with identify:

magick identify input.jpg

If identify also fails, the file is damaged. Check whether the file extension matches the actual format:

file input.jpg

The file command (Linux/macOS) reads the file header and reports the real format regardless of the extension. On Windows, use magick identify instead, which reports the detected format in its output.

If the format doesn’t match the extension, rename the file or convert it explicitly:

magick PNG:input.jpg output.jpg

The PNG: prefix forces ImageMagick to read the file as PNG regardless of the .jpg extension.

Fix wrong-looking output

Colors look wrong after conversion

Cause: The source image is in CMYK colorspace (common in files from print workflows), and the output was not explicitly converted to RGB. Some viewers display CMYK data as inverted or shifted colors.

Fix: Check the colorspace of the input:

magick identify -format '%[colorspace]' input.jpg

If it reports CMYK, convert explicitly:

magick input.jpg -colorspace sRGB output.jpg

Without -colorspace sRGB, ImageMagick may preserve the CMYK data in the output file. Programs expecting RGB will display the colors incorrectly.

Transparent areas turn black

Cause: You converted a PNG with transparency to JPEG (or another format that does not support alpha channels). ImageMagick fills transparent areas with the default background color, which is black.

Fix: Flatten the image onto a white (or any other color) background before converting:

magick input.png -background white -flatten output.jpg

-background white -flatten composites the image onto a white canvas, replacing all transparent areas before writing the JPEG.

Image appears rotated or sideways

Cause: The source image has an EXIF orientation flag that your viewer respects, but ImageMagick did not apply it during processing. The pixel data is still in the camera’s native orientation.

Fix: Add -auto-orient before any other operations:

magick input.jpg -auto-orient -resize 800x600 output.jpg

-auto-orient reads the EXIF orientation flag, physically rotates the pixels to match, and removes the flag.

.webp file looks wrong or viewers say it is JPEG

Symptom: You wrote output.webp, nothing errored, but the image looks like JPEG compression or tools report JFIF / JPEG inside the file.

Cause: Some builds lack a WebP encode delegate. ImageMagick may still write a file with a .webp extension while encoding with another codec; the extension can lie.

Fix:

• Run magick --version and read Delegates (built-in): you should see webp if WebP encode is native to this binary.
• Run magick identify -verbose output.webp | Select-String -Pattern 'format|mime' (or grep on Linux/macOS). If the reported format is JPEG despite the .webp name, install a build with WebP support or write to output.jpg until you upgrade.

magick -list format | grep -i webp

You want a line with WEBP and rw (or at least read) for the direction you need.

Output file is larger than the input

Cause: Converting between formats can increase file size. PNG is lossless and often larger than JPEG for photographic images. Resizing upward increases file size. Converting from a lossy format to another lossy format at high quality can also increase size.

Fix: Set an explicit quality level:

magick input.jpg -quality 85 output.jpg

The numeric scale depends on the output format; see -quality for how to read and tune it. Lower values usually mean smaller files and more visible compression. For JPEG, you can also set a file size ceiling:

magick input.jpg -define jpeg:extent=200KB output.jpg

Fix platform-specific problems

Shell interprets >, <, ^, or ! in geometry strings

Cause: Characters like >, <, ^, and ! have special meaning in bash, PowerShell, and cmd. An unquoted 800x600> redirects output to a file named 600 instead of passing the string to ImageMagick.

Fix:

Linux / macOS

Wrap geometry strings in single quotes:

magick input.jpg -resize '800x600>' output.jpg

Or escape with a backslash:

magick input.jpg -resize 800x600\> output.jpg

Windows (PowerShell)

Wrap geometry strings in double quotes:

magick input.jpg -resize "800x600>" output.jpg

Windows (cmd)

Use the caret (^) to escape special characters:

magick input.jpg -resize 800x600^> output.jpg

For the ^ geometry flag itself, double it:

magick input.jpg -resize "800x600^^" output.jpg

Parentheses cause errors on Windows

Cause: ImageMagick uses ( and ) for image sequence grouping. In cmd, parentheses are control characters.

Fix: In cmd, escape with ^:

magick ^( -size 300x60 xc:none -annotate 0 "text" ^) overlay.png

In PowerShell, wrap in quotes or use the backtick:

magick `( -size 300x60 xc:none -annotate 0 "text" `) overlay.png

If your issue is resolved, pick up where you left off: tutorial, batch resize guide, Geometry syntax reference, or common options reference. For problems not covered here, search the GitHub Discussions.