Skip to content

Troubleshooting

Jump to bottom
Aaron Liu edited this page Jul 2, 2025 · 35 revisions

If you run into problems with Upscayl, here are a few ways to fix it.

Table of Contents:

Important

You'll need a Vulkan compatible GPU to upscale images. Many CPU and iGPUs do not work but no harm in trying. A GPU is usually either from Nvidia, named an "Arc", or named with the letter R followed by a number or X; anything else is probably an incompatible CPU, which may work but only slowly with a workaround.

Make sure to read the FAQ first to avoid getting rickrolled.

🔨 General Fixes

  • Update the app.
    • Uninstall and Reinstall the app.
  • Restart your computer.
  • Try setting your GPU ID to your discrete GPU.

🖖 Vulkan error code troubleshooting

For errors that say "vk<something> failed -" in the log, consult https://registry.khronos.org/vulkan/specs/latest/man/html/VkResult.html.

  • For VK_ERROR_OUT_OF_HOST_MEMORY (-1), this is probably due to a CPU memory leak we are still investigating.
  • For VK_ERROR_OUT_OF_DEVICE_MEMORY (-2), try giving your GPU less memory in the BIOS, which somehow helped this lucky guy. If that fails then give it more memory like a normal person.
  • For VK_ERROR_INCOMPATIBLE_DRIVER (-9), triple check your drivers.

🎨 Drastic color changes

Upscayl making an image's color much less vibrant Upscayl currently only supports the sRGB color profile. If an image with a different color profile is input, the output may become drastically "washed out". To fix this, convert the input image to the sRGB color profile before upscayling.

🐧 Linux Users

  • Make sure graphics drivers are installed, including Vulkan drivers. See https://linuxconfig.org/install-and-test-vulkan-on-linux for details.
    • The article doesn't include instructions for Intel on Arch Linux for some reason. Install vulkan-intel in this situation.
  • Reinstall graphics drivers BUT Before doing that, run VulkanCapsViewer. If it reports Vulkan support, you might not need to do this.

🍎 Mac Users

  • Make sure you're using the latest MacOS update.
  • If Upscayl refuses to launch, follow these steps:
Click here to view the steps

If the app doesn't work, try deleting all its files and folders:

  1. Open Finder → Click Go in the menu bar → Select Go to Folder from the drop-down menu → In the window that appears, type ~/Library/ and press Enter.

  2. Here, in the Library folder, find and remove all files which contain 'Upscayl'. Here's a list of files and folders you can safely delete:

⚠️ PLEASE DO NOT DELETE THE FOLDERS THAT DO NOT HAVE UPSCAYL IN THEIR NAME

  • ~/Library/Application Support/Upscayl
  • ~/Library/Saved Application State/org.upscayl.Upscayl.savedState/
  • ~/Library/Group Containers/W2T4W74X87.org.upscayl.Upscayl
  • ~/Library/Containers/Upscayl (and other folders named Upscayl)
  • ~/Library/Preferences/org.upscayl.Upscayl.plist/
  • ~/Library/Preferences/org.upscayl.Upscayl.helper.plist/

🪟 Windows Users

If all of the above fail, Please click here to know how you can ask for help.

Clone this wiki locally