> ## Documentation Index
> Fetch the complete documentation index at: https://hackmamba-3f164318.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<AccordionGroup>
  <Accordion title="Linux / macOS (bash)">
    ```bash theme={null}
    # 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
    ```
  </Accordion>

  <Accordion title="Windows (PowerShell)">
    ```powershell theme={null}
    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.
  </Accordion>
</AccordionGroup>

## Fix error messages

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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:

    ```bash theme={null}
    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](/quickstart#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.
  </Accordion>

  <Accordion title="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:

    <Tabs>
      <Tab title="Linux / macOS">
        ```bash theme={null}
        magick -list format | grep -i heic
        ```
      </Tab>

      <Tab title="Windows (PowerShell)">
        ```powershell theme={null}
        magick -list format | Select-String -Pattern heic -CaseSensitive:$false
        ```
      </Tab>
    </Tabs>

    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.
  </Accordion>

  <Accordion title="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:

    <Tabs>
      <Tab title="Linux / macOS">
        ```bash theme={null}
        magick -list format | grep -i heic
        ```
      </Tab>

      <Tab title="Windows (PowerShell)">
        ```powershell theme={null}
        magick -list format | Select-String -Pattern heic -CaseSensitive:$false
        ```
      </Tab>
    </Tabs>

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

  <Accordion title="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:

    ```bash theme={null}
    magick -list resource
    ```

    Increase limits for the current command using `-limit`:

    ```bash theme={null}
    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:

    <Tabs>
      <Tab title="Linux / macOS">
        ```bash theme={null}
        magick -list policy | head -25
        ```
      </Tab>

      <Tab title="Windows (PowerShell)">
        ```powershell theme={null}
        magick -list policy | Select-Object -First 25
        ```
      </Tab>
    </Tabs>

    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:

    ```xml theme={null}
    <policy domain="resource" name="memory" value="2GiB"/>
    <policy domain="resource" name="disk" value="4GiB"/>
    ```
  </Accordion>

  <Accordion title="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.

    <Warning>
      **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.
    </Warning>

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

    <Tabs>
      <Tab title="Linux / macOS">
        ```bash theme={null}
        magick -list policy | head -40
        ```
      </Tab>

      <Tab title="Windows (PowerShell)">
        ```powershell theme={null}
        magick -list policy | Select-Object -First 40
        ```
      </Tab>
    </Tabs>

    **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:

    ```xml theme={null}
    <policy domain="coder" rights="none" pattern="PDF" />
    ```

    to:

    ```xml theme={null}
    <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.
  </Accordion>

  <Accordion title="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`:

    ```bash theme={null}
    magick identify input.jpg
    ```

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

    ```bash theme={null}
    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:

    ```bash theme={null}
    magick PNG:input.jpg output.jpg
    ```

    The `PNG:` prefix forces ImageMagick to read the file as PNG regardless of the `.jpg` extension.
  </Accordion>
</AccordionGroup>

## Fix wrong-looking output

<AccordionGroup>
  <Accordion title="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:

    ```bash theme={null}
    magick identify -format '%[colorspace]' input.jpg
    ```

    If it reports `CMYK`, convert explicitly:

    ```bash theme={null}
    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.
  </Accordion>

  <Accordion title="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:

    ```bash theme={null}
    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.
  </Accordion>

  <Accordion title="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:

    ```bash theme={null}
    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.
  </Accordion>

  <Accordion title=".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.

    ```bash theme={null}
    magick -list format | grep -i webp
    ```

    You want a line with **`WEBP`** and **`rw`** (or at least read) for the direction you need.
  </Accordion>

  <Accordion title="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:

    ```bash theme={null}
    magick input.jpg -quality 85 output.jpg
    ```

    The numeric scale depends on the output format; see [-quality](/reference/common-options#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:

    ```bash theme={null}
    magick input.jpg -define jpeg:extent=200KB output.jpg
    ```
  </Accordion>
</AccordionGroup>

## Fix platform-specific problems

<AccordionGroup>
  <Accordion title="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:**

    <Tabs>
      <Tab title="Linux / macOS">
        Wrap geometry strings in single quotes:

        ```bash theme={null}
        magick input.jpg -resize '800x600>' output.jpg
        ```

        Or escape with a backslash:

        ```bash theme={null}
        magick input.jpg -resize 800x600\> output.jpg
        ```
      </Tab>

      <Tab title="Windows (PowerShell)">
        Wrap geometry strings in double quotes:

        ```powershell theme={null}
        magick input.jpg -resize "800x600>" output.jpg
        ```
      </Tab>

      <Tab title="Windows (cmd)">
        Use the caret (`^`) to escape special characters:

        ```cmd theme={null}
        magick input.jpg -resize 800x600^> output.jpg
        ```

        For the `^` geometry flag itself, double it:

        ```cmd theme={null}
        magick input.jpg -resize "800x600^^" output.jpg
        ```
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="Parentheses cause errors on Windows">
    **Cause:** ImageMagick uses `(` and `)` for image sequence grouping. In cmd, parentheses are control characters.

    **Fix:** In cmd, escape with `^`:

    ```cmd theme={null}
    magick ^( -size 300x60 xc:none -annotate 0 "text" ^) overlay.png
    ```

    In PowerShell, wrap in quotes or use the backtick:

    ```powershell theme={null}
    magick `( -size 300x60 xc:none -annotate 0 "text" `) overlay.png
    ```
  </Accordion>
</AccordionGroup>

If your issue is resolved, pick up where you left off: [tutorial](/tutorials/build-image-processing-pipeline), [batch resize guide](/how-to/batch-resize-and-optimize), [Geometry syntax reference](/reference/geometry), or [common options reference](/reference/common-options). For problems not covered here, search the [GitHub Discussions](https://github.com/ImageMagick/ImageMagick/discussions).