Skip to main content

​
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.
There is no built-in file command; magick identify already reports the detected format.

​
Fix error messages

Error:
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.
Cause: ImageMagick 7 is not installed, or the magick binary is not on your system PATH.Fix: Verify which version you have:
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.
Error:
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:
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.
Error:
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:
A line showing r-- means read-only. You need a build with write support (rw- or rw+), or convert to a different output format.
Error:
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:
Increase limits for the current command using -limit:
To change defaults permanently, edit the policy.xml file (or the policy fragment your packager uses). Find active policy paths with:
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:
Error:
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):
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):Fix (step 3): Find the restrictive line and change rights only if you accept the risk above:
to:
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.
Error:
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:
If identify also fails, the file is damaged. Check whether the file extension matches the actual format:
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:
The PNG: prefix forces ImageMagick to read the file as PNG regardless of the .jpg extension.

​
Fix wrong-looking output

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:
If it reports CMYK, convert explicitly:
Without -colorspace sRGB, ImageMagick may preserve the CMYK data in the output file. Programs expecting RGB will display the colors incorrectly.
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:
-background white -flatten composites the image onto a white canvas, replacing all transparent areas before writing the JPEG.
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:
-auto-orient reads the EXIF orientation flag, physically rotates the pixels to match, and removes the flag.
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.
You want a line with WEBP and rw (or at least read) for the direction you need.
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:
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:

​
Fix platform-specific problems

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:
Wrap geometry strings in single quotes:
Or escape with a backslash:
Cause: ImageMagick uses ( and ) for image sequence grouping. In cmd, parentheses are control characters.Fix: In cmd, escape with ^:
In PowerShell, wrap in quotes or use the backtick:
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.