Known Issues is a list of unusual problems that can be quite challenging to diagnose and solve from scratch. We keep this list mainly for our own use in providing support, but we're making it publicly available in case it may be useful to other people also.

If you encounter difficulties that are not on this list, or if the suggested workarounds do not work for you, then please contact support@zerenesystems.com. We try hard to fix problems, but we have to know about them first!

Here is an index to the known issues:

• macOS Big Sur, System Preference for "Prefer tabs" can hang Zerene Stacker.
• License keys that contain accented or non-English characters may get corrupted in email transmission.
• Settings are retained across uninstall/reinstall.
• License key must be installed for each user account.
• 16-bit TIFF files should be uncompressed.
• Certain grayscale images may cause "incompatible ColorModel".
• ZoneAlarm Toolbar may significantly reduce available memory.
• Added physical memory is not seen by Zerene Stacker.
• To process large images at full resolution, you must increase the memory allocation above the default values.
• Continuous backup or indexing may interfere with image caching.
• Must use double-click, not the Open button, to navigate into a folder when using File > Open Project .
• Windows, "My Documents" and "My Pictures" may not be writable.
• Windows, cannot navigate through a shortcut.
• Windows, manually edited program files persist across re-installation.
• Macintosh macOS Monterey, application silently fails to launch.
• Macintosh OS X, "Could not establish communications with StackShot controller".
• Macintosh OS X, Zerene Stacker will work on only one stack at a time.
• Macintosh OS X (Mountain Lion) reports installation bundle is "damaged, move to trash".
• Macintosh OS X, how to recover from excessive memory allocation.
• Macintosh OS X, TIFF files may be very slow to read.
• Macintosh OS X, accessing external drives may be awkward.
• Macintosh OS X, launch fails due to Courier font problems.
• Macintosh OS X, JPEG files with color profile "Nikon sRGB 4.0.0.3001" will be dark and muddy.
• Linux, use of native Look & Feel with Ubuntu Studio theme fails.

Solved issues, retained here for historical reasons.

• Very large TIFF files may require "Use External TIFF Reader".
• Red "RasterFormatException" occurs during retouching.
• Graphics "acceleration" sometimes makes the retouching brush very slow and jerky.
• Retouching brush disappears.
• External TIFF reader cannot handle commas in file or directory names.
• Macintosh OS X, the downloaded bundle runs once but not again.
• Using Capture One raw converter, must turn off option to "Embed Camera Profile".

Beginning with macOS “Big Sur” (macOS 11, also known as 10.16) it is critical that System Preferences > General > “Prefer tabs: … when opening documents” must be set to either “never” or “in full screen”. Further, if you select “in full screen”, then do not run Zerene in full screen mode.

These restrictions are because there is a new bug, introduced in macOS Big Sur, that causes Zerene Stacker (and all other Java programs) to display a grossly oversized window and become nonresponsive, whenever the application tries to open a non-blocking dialog. In Zerene Stacker, such dialogs include the DMap contrast threshold slider, the StackShot controller panel, and the DOF and stereo calculators.

The safest setting for “Prefer tabs” is “never”. The most dangerous setting is “always”, which as of this writing (Feb 2021) will cause Zerene Stacker to hang if it tries to open any of the dialogs listed earlier.

When Zerene Stacker is hung because of this problem, you may not be able to get a Force Quit menu by mouse action. However, the keyboard combination Cmd-Option-Escape will still work to bring up a Force Quit menu, in which you can select Zerene Stacker and then Force Quit it.

If the username in the license key looks odd, and the Enter button stays gray when you paste in your license key, try just retyping the name to match what you entered when you purchased the license. Further details are provided in How To Install a License Key.

If that doesn't work, then please contact support@zerenesystems.com and we'll get the problem taken care of.

On Windows, the uninstaller program removes only folders and files that it created. This causes some state information to be retained, so that uninstall/reinstall will not restore the program to a factory-fresh condition. To get back to a factory-fresh condition, you must uninstall, then manually remove one folder and the files it contains, before reinstalling.

Note that this will also uninstall your license key, so be sure you have a copy of that saved first. If you do not already have a separate copy of your license key, you can make one by running Zerene Stacker and extracting the key using copy/paste at Options > Registration.

The folder you need to remove is in the “application data” area of your profile. Go to Start > Run and open %APPDATA%. This will open a Windows Explorer to view a folder named something like “C:\Documents and Settings\username\Application Data” or “C:\Users\username\AppData\Roaming”. Within that folder, select and delete the folder named ZereneStacker.

On Windows 10, usually it is not possible to open the Start > Run dialog. Instead, you can open a File Explorer window, then in that window's address bar, type in %APPDATA% and hit the Enter key. On some systems, it is also necessary to set the folder view options to “Show hidden files, folders, and drives”. See for example http://www.windows10themes.net/guides/how-to-view-the-appdata-folder-in-windows-10/

On Macintosh OS X, dragging the application bundle to the trash leaves behind some state information in other files and folders, so that reinstalling the program will not restore the program to a factory-fresh condition. To get back to a factory-fresh condition, you must manually remove one folder and the files it contains, before reinstalling. The folder you need to remove is ~/Library/Preferences/ZereneStacker, where ~ denotes your account's home directory. Note that the ~/Library folder is normally hidden. To open it, hold down your keyboard's Option (Alt) key while selecting Go > Library in a Finder window. Once you have the ~/Library folder, then find and go into the Preferences folder. From there, the ZereneStacker folder will be at the bottom of the list, or very close to it. Be careful that you do not remove other folders or files in ~/Library/Preferences, because these contain settings for other programs.

Note that removing ~/Library/Preferences/ZereneStacker will also uninstall your license key, so be sure you have a copy of that saved first. If you do not already have a separate copy of your license key, you can make one by running Zerene Stacker and extracting the key using copy/paste at Options > Registration.

On Linux, it is the same situation as on Macintosh OS X except that the folder you need to remove is ~/.ZereneStacker (note the dot – this directory is normally “hidden”).

If the product is licensed for multiple users, each user will need to install his or her own copy of the license key. Until this is done, each new user will see Zerene Stacker as running in Trial Mode.

On most systems, each user will also need to set memory allocation. On old Macintoshes, memory allocation is maintained in a different way that makes one setting apply to all users.

Zerene Stacker cannot directly read 16-bit TIFF files that have been Zip-compressed. Such files may be produced, for example, by Adobe Lightroom or Photoshop, if the file export compression is set to “ZIP” as opposed to “None” or “LZW”.

Attempting to load such a file into Zerene Stacker will produce the following diagnostic:

          javax.imageio.IIOException: 16-bit samples are not supported for Horizontal differencing Predictor
          at com.sun.media.imageioimpl.plugins.tiff.TIFFDeflateDecompressor.decodeRaw(Unknown Source)

This problem can be worked around by selecting Options > Preferences > Preprocessing > Use External TIFF Reader. (If you do not explicitly select this option, then the current version of Zerene Stacker should automatically fall back to using this approach anyway.)

However, it is usually more efficient to set the file format in Photoshop or Lightroom to “None” or “LZW” so that the file can be read directly, then in Zerene Stacker de-select the option to Use External TIFF Reader.

Some grayscale images may cause Save Output Image(s) to fail with a diagnostic like this:

    java.lang.IllegalArgumentException: Raster ShortInterleavedRaster: width = 1504 height = 1242
    #numDataElements 3 is incompatible with ColorModel ColorModel: #pixelBits = 16 numComponents = 1
    color space = java.awt.color.ICC_ColorSpace@5c3f1224 transparency = 1 has alpha = false isAlphaPre = false
    at java.awt.image.BufferedImage.<init>(Unknown Source)

The workaround is to select Options > Preferences > Color Management > “Do not manage color”.

If you do not explicitly select this option, then the current version of Zerene Stacker should automatically fall back to “Do not manage color” anyway. Please let us know if you observe this problem again.

Simply installing the ZoneAlarm Toolbar may reduce the maximum Zerene Stacker memory allocation by several hundred megabytes. This is due to address space fragmentation caused by one of the ZoneAlarm's DLLs (ISWSHEX.dll, hard-loaded at address 0x20cb0000) . ZoneAlarm has been notified of the problem, but at present their only workaround is to un-install the Toolbar.

Update: In the latest release of ZoneAlarm Internet Security Suite version 10.0.250.000, even removing the Toolbar is not sufficient — ISWSHEX.dll is loaded anyway. We are not aware of a workaround in this latter case, except of course to uninstall ZoneAlarm and use a different security product that avoids such application-unfriendly behavior.

In either case, note that after uninstalling ZoneAlarm, you'll have to press Set Automatically at Options > Preferences > Memory Usage, in order to change Zerene Stacker's allocation to the new larger value.

Changes in the amount of physical memory in your computer may not be seen by Zerene Stacker, even if the Memory Usage panel explicitly says that memory “has been detected automatically”.

To correct this problem, simply go to Options > Preferences > Memory Usage.

At first, the field labeled “Megabytes of physical memory in this computer” will probably be grayed out. To make it black and adjustable, hover your cursor over the little period at the end of the line. That will cause a button to appear, labeled “Detect”. When you press the Detect button, Zerene Stacker will ask the computer's operating system how much memory it thinks is installed. In the unlikely event that added physical memory is still not seen, or if the automatically detected value is not correct, then again hover over the period to make the number black and adjustable, but this time instead of pressing the Detect button, simply click into the number field and enter the proper value by hand.

The process is shown below.

Red arrow indicates the place to hover over the little period (“.”) .

The “Detect” button then appears, and the value field become black and adjustable:

When you Add File(s), you may receive a popup window that looks something like the following:

If you proceed without pre-sizing and without increasing the memory allocation, then you are likely to encounter the following error (“Out of memory, cannot proceed”):

The cure for this problem is to allocate more memory using Options > Preferences > Memory Usage. Pressing the Set Automatically button works for most people, but if your images are very large then you may need to manually enter a larger value. The recommended allocation is 100 to 200 megabytes per 1 megapixel, so for example 3600 to 7200 megabytes for 36 megapixel images coming from a Nikon D800.

Images larger than 21 megapixels will probably require using the 64-bit version of Zerene Stacker, on a 64-bit operating system.

When the look-and-feel option to use JFileChooser is selected, and you have done File > Open Project and you want to look inside a folder to find your project, it does not work to select the folder and click the Open button. Instead of doing what you want, clicking the Open button will attempt to open the folder as if it were a project. This produces a cryptic and misleading error message: “Cannot open project because .zsj project description file is missing”. To get the desired result of opening the folder to look inside it, you must double-click the folder name instead of clicking the Open button.

Alternatively, you may prefer to use your operating system's file browser to locate and select the project, then drag-and-drop it onto the Input Files panel of Zerene Stacker. This is equivalent to File > Open Project. When doing this, you can select either the .zsj project description file or the folder that encloses it. Again, these are equivalent when opening a project.

Some backup and indexing facilities have the unfriendly behavior of briefly grabbing a file in exclusive-access mode immediately after it is created. This can interfere with Zerene Stacker's caching of image files, because ZS often attempts to read these files immediately after they've been created, and if another process has grabbed them, it can't.

The problem appears as a red “Uh-oh” popup, with a detail diagnostic like this:

          java.io.FileNotFoundException:  C:\Users\Me\Pictures\unnamedZSproj20111103154858382\previewimages\-Unaligned-117.jpg (Access is denied)
          at java.io.RandomAccessFile.open(Native Method)

There are several possible workarounds for the problem:

1. Turn off or pause the backup or indexing facility while ZS is running.
2. Configure the backup or indexing facility to have a longer delay between file creation and backup.
3. Configure it to not backup or index some specified directory, then in ZS use Options > Preferences > New Projects to place new projects in that directory.
4. In ZS, go to Options > Preferences > Image caching, and un-check both options. This will make the initial stacking go somewhat faster, but will make subsequent reviewing and retouching much slower. In addition, this option still leaves open the same sort of vulnerability on the .zsy files that are used to store output images.

On Windows, if the problem is caused by an indexing plugin, then one way to work around the problem is this:

1. Click Start > … on the Windows taskbar.
2. Type “services.msc” into the Open box, then click OK. “Services” panel will pop up.
3. In the Services panel, scroll down and select Windows Search. The Description will say “Provides content indexing, …”.
4. In the upper left part of that panel, click on “Stop the service”.
5. Run your stack.
6. Back in the Services panel, click on “Start the service”.

A similar problem can be caused during file saving, when Zerene Stacker attempts to copy Exif metadata from a source image file into the just-saved output image file.

On some Windows systems, special folders such as “My Documents” are erroneously marked as “Read Only”. Most applications never notice, but Zerene Stacker honors the “Read Only” status for these folders and refuses to create files or new folders in them.

One cure for this problem is to use an arcane Windows command to clear the “Read Only” status for those folders. Simply open a Command Prompt window (using for example Start > Run… > cmd), then type the following commands:

          attrib -r "%USERPROFILE%\My Documents"
          attrib -r "%USERPROFILE%\My Documents\My Pictures"

It is only necessary to run these commands one time.

Alternatively, you can use Windows Explorer to create new folders, which Zerene Stacker can then write into.

On Windows, the filechooser dialogs popped up by Zerene Stacker may not be able to navigate through a shortcut. This is due to a bug in the Java Runtime Environment. The problem is diagnosed by a generic “Uh-oh – something went wrong” popup, with a red-highlighted error message in the console log like this:

    Exception occurred during event dispatching:
    java.lang.InternalError: Unable to bind F:\ZereneSystems\TestStacks\FruitFlyFace - Shortcut.lnk to parent
       at sun.awt.shell.Win32ShellFolder2$4.call(Unknown Source)

There are two workarounds: either access your folders using a path that does not involve a shortcut, or where possible use drag-and-drop.

Note: using the default look and feel, there is a button labeled “Recent Items” near the upper left corner of the filechooser dialog. The items that get listed when you click that button look like ordinary folders, but they are really shortcuts. Clicking any one of them will produce the error shown above. To avoid the problem, you must avoid using the Recent Items button, in addition to items in any other folder that are explicitly shown as being shortcuts.

On Windows, if any files in C:\Program Files or C:\Program Files (x86) are manually edited, then those edits will persist across reinstallation of Zerene Stacker, even if Zerene Stacker is completely uninstalled first. This is caused by an annoying feature of Windows called the “virtual store”. Contrary to appearances, the original file was not actually edited, but instead it became shadowed by a second file containing the edited version. When the software is uninstalled, the second file remains. Then when the software is re-installed, the second file again shadows the newly re-installed version, so the edited version mysteriously reappears. There seems to be no way to get rid of the second file except by logging in as Administrator, navigating to the virtual store, and explicitly removing the file there. The virtual store is located at C:\Users\<username>\Appdata\Local\VirtualStore\Program Files\ZereneStacker . You must be logged in as Administrator to even see this directory.

Older builds of Zerene Stacker may silently fail to launch under macOS Monterey. The underlying cause is a small change in macOS, which was accommodated in Zerene Stacker at Build T2021-07-31-1138 (July 31, 2021). This launch problem will be fixed by updating your copy of Zerene Stacker to the latest build.

In gory detail, here are instructions to update Zerene Stacker:

1. Move to Trash all copies of ZereneStacker that you have now.
2. Remove any ZereneStacker icons, for example on the taskbar/dock.
3. Using Safari, download a fresh copy of the distribution .zip from https://zerenesystems.com/cms/stacker/softwaredownloads .
4. Use Finder to open the Downloads folder. (Do not use the “Open downloads” icon inside Safari.)
5. Probably the .zip download has already been unpacked to form the “yellow smiling dog face” icon named ZereneStacker.
6. But if it has not, then unpack the .zip file manually. Be sure to do this unpack inside the Downloads folder.
7. Using Finder, move the “yellow smiling dog face” ZereneStacker icon from Downloads to Applications.
8. If you are using the Lightroom plugin, then you must also update that as follows:
   • Be sure that Lightroom is not running.
   • Launch Zerene Stacker from its icon in Applications.
     This may automatically update the Lightroom plugin to match the new version of Zerene Stacker.
     If it does not, then go to Options > Plugins > Lightroom, and click either “Create plugin, standard location” or “Create plugin, specified location”, depending on how you had the Lightroom installed before the update.
   • Quit ZereneStacker.
   • Launch Lightroom and confirm that you can Export to Zerene Stacker.

(Note: recent versions of Zerene Stacker contain code to automatically detect and work around this problem, requiring no input from the user other than to provide a password. However, we're leaving this description in place, in case some future situation may require the same information to be used in some slightly different manner. Please let us know if you encounter difficulties.)

On Macintosh, especially OS X 10.9 (Mavericks), attempting to do a Tools > StackShot… may fail with a popup diagnostic that says “Could not establish communications with StackShot controller. StackShot not found. (USB unplugged?)” even though a System Report of the USB Device Tree shows that a StackShot is present. Further symptoms are that ls /dev/*serial* will show a device named tty.usbserial-FTSERIAL, where FTSERIAL exactly matches the StackShot's “Serial Number” as shown in the StackShot details of the Mac's System Report > USB Device Tree.

This problem is caused by a conflict between two different families of device drivers for the FTDI USB interface chip used in the StackShot controller. The StackShot is designed to use the D2XX drivers, which are bundled inside Zerene Stacker. But some other devices need the VCP drivers, which are installed into the operating system as “kernel extensions”. Unfortunately, the VCP drivers grab access to the StackShot as soon as it is plugged in, and then they prevent Zerene Stacker from being able to access the StackShot through D2XX. In Mac OS X 10.8 and below, VCP drivers were installed only by third-party software such as the Arduino development kit. However, starting with Mac OS X 10.9 (Mavericks), VCP drivers are also provided directly by Apple as part of the standard distribution. As a result, the StackShot will not work with Zerene Stacker on Mavericks or Yosemite unless the VCP drivers are disabled.

You can temporarily disable the VCP drivers as follows.

• First, be sure that your StackShot is powered on and plugged in to a USB port. The StackShot controller should be showing “PC” in its upper right corner.
• Then, open a Terminal window and enter the following commands:

sudo kextunload -b com.apple.driver.AppleUSBFTDI
sudo kextunload -b com.FTDI.driver.FTDIUSBSerialDriver

You will have to enter your normal account password (the same one you use to login to Mac OS X). The first command is needed to unload the driver provided by Apple in OS X 10.9. The second command is needed to unload the driver provided by FTDI and installed by other software. If one or the other of these drivers was not present to start with, then the kextunload command will fail but this is harmless.

After execution of the kextunload commands, the device /dev/tty.usbserial-FTSERIAL will disappear, and then Zerene Stacker will be able to access the StackShot.

The above fix is temporary. The VCP drivers will be loaded again when the system is restarted or powered up.

The VCP drivers can also be permanently disabled so they will not automatically load on restart or power up. However, that process is somewhat more complicated and has potential side effects. If you want to go that route, please contact support@zerenesystems.com for further information.

Note: In some cases, simply executing the above two kextunload commands does not allow Zerene Stacker to communicate with the StackShot. In that case support@zerenesystems.com will need some further information to figure out what's going wrong. Please perform the following steps:

1. Reboot your Mac.

2. Be sure that your StackShot is connected and powered on. It should say “PC” in the extreme upper right of its own display.

3. Go to (apple icon) > About This Mac > More Info… > System Report… > Hardware > USB. Look through the list of devices for a StackShot. If you find one, then make a snapshot of the screen and send that to us.

4. Open a Terminal window and enter the following command: ls /dev/*serial*
Send us the output listing.

5. Try the two kextunload commands again. It's normal for one of them to fail. Send us all the output from the Terminal window.

6. Launch Zerene Stacker, try to connect to the StackShot, then after you get the error message, exit normally from Zerene Stacker. After Zerene Stacker exits, locate and send to us the latest console log that was saved by Zerene, as described HERE . If you have not received a red popup “Uh-oh” message, then LastNormalLog.txt is what we need to see. In any case, it's the file named *Log* with the latest timestamp.

Interestingly, in most cases just going through the above steps to collect the required information also makes the problem disappear. That probably has to do with the reboot and order of operations.

Solution: open a Terminal window and launch additional copies of Zerene Stacker using the command

open -n /Applications/ZereneStacker.app 

If you put the ZereneStacker icon (the ZereneStacker.app application bundle) someplace besides in /Applications, then just edit the command line accordingly.

The explanation here is that by design, Zerene Stacker is programmed using the “single document” model. This means that each instance of Zerene Stacker can only work with one stack at a time. The normal process of launching Zerene Stacker by clicking its icon will not launch a second instance. Instead, clicking the icon just makes the current instance foreground, apparently in the expectation that all programs are multi-document. Unfortunately there seems to be no way to just tell MacOS that Zerene Stacker is single document and it should launch another instance when the launch icon is clicked. The “-n” argument on the open command says to create a new instance regardless of whether there's already one running.

Note: All recent versions of Zerene Stacker are digitally signed in such a way as to avoid this problem. However, we're leaving this description in place in case a similar problem resurfaces at some point. Please let us know if you encounter one.)

The symptom here is that when Mountain Lion finishes downloading a Zerene Stacker application bundle such as ZS-MacOSX-T201207281315.zip, it reports that the file is “damaged” and that you have to “move it to the trash”.

In fact, the file is not damaged and it will run fine under Mountain Lion if the download security settings are temporarily changed to “Anywhere”. Detailed instructions to accomplish this (for a different product) are provided at http://wiki.espeakers.com/index.php/OS_X_Mountain_Lion_installation_instructions.

What has happened is that Apple has changed their malware detection to err on the side of caution and report “damaged” unless they can confirm via digital signature that the file is not damaged.

Zerene Stacker distributions prior to ZS-MacOSX-SA-T201207281315.zip were not digitally signed, so they will always trigger the “damaged” message on Mountain Lion or other systems with the same security settings.

Starting with ZS-MacOSX-SA-T201207281315.zip, the distributions are digitally signed and will install without complaint on almost all systems. We have heard of one Mountain Lion installation where even the signed distribution encountered the “damaged” message and it was necessary to use the workaround of temporarily changing the download security settings.

If you need more information about this issue, please contact support@zerenesystems.com .

Under most circumstances, the Options > Preferences > Memory Usage control panel will prevent you from specifying a larger memory allocation than your computer can actually support. Under unusual circumstances it is possible to specify too large a value. In this case, subsequent launches of Zerene Stacker will fail with some diagnostic like “The application ZereneStacker quit unexpectedly.”

The simplest cure for this problem is the following: Download and install a fresh copy of Zerene Stacker. Launch it. You will receive a diagnostic popup that says “Memory allocation has been reset following a software update. You must exit and re-launch the application to use the new allocation.” Do not exit the application at this time! Instead, proceed to Options > Preferences > Memory Usage, click the Set Automatically button, then click the OK button. Exit the application, re-launch, and everything should be fine again.

In very rare cases, the re-launch may fail because the computer cannot allocate the amount of memory that the Set Automatically button requests. If this occurs, then repeat the previous procedure, but instead of clicking Set Automatically, simply type the value 1000 into the field labeled “Megabytes of memory currently allocated to 32-bit Zerene Stacker”. Click OK, exit, and re-launch.

On Macs, Zerene Stacker normally attempts to open a Finder window to use as a helper service for navigating and selecting files. On a few Macs, for unknown reasons, the Finder window refuses to open. In that case, Zerene Stacker automatically switches to a different method, using a facility named “JFileChooser” that is part of the Java Runtime Environment that Zerene Stacker runs on top of. (The use of JFileChooser can also be selected explicitly, by removing the checkmark at Options > Preferences > Look & Feel > “Use system native File Choosers if possible”.)

Unfortunately the JFileChooser interface looks much different from Finder, and it requires more mouseclicks to access drives other than the default.

To access alternate drives using JFileChooser, proceed as follows:

1. Open a JFileChooser window, for example by File > Add File(s) or File > Save Output Image(s).
2. Go to the bar at the top of the window, the one where the current folder is shown. Click on that bar and it will expand into a pull-down list of enclosing folders.
3. At the top or bottom of the list will be an entry like “/” or “Macintosh HD”, representing the main file system of the computer. Click that to open it.
4. Scroll to the bottom of the list and double-click on Volumes. That should open to give you a list of all your currently mounted media.
5. Double-click on any external drive to open that, then navigate as usual.

Also, note that when using JFileChooser, you must use double-click, not the Open button, to go inside a folder. For further explanation about this issue, see "Must use double-click, not the Open button, to navigate into a folder when using File > Open Project".

Zerene Stacker may fail to launch on Mac OS X due to font problems. A typical message appearing in the system console log is:

  Warning: the font "Courier" is not available, so "Lucida Sans Typewriter" has been substituted, 
  but may have unexpected appearance or behavor. Re-enable the "Courier" font to remove this warning. 

Check in the font manager to be sure that you have exactly one Courier font installed and active. Despite the phrasing of the message, having two or more Courier fonts installed is also a problem.

On PowerPC systems, most TIFF files are slow to read and 16-bit TIFF files are particularly bad. At this time the only workaround on PowerPC systems is to make copies of your TIFF files as highest quality JPEG, converting 16-bit to 8-bit if necessary, then stack the JPEG copies.

Intel Macs should read TIFF files quickly (seconds per image), if Options > Preferences > Preprocessing > Use External TIFF Reader is selected. This is the default setting. If this option is not selected, then some types of TIFF files will read very slowly (minutes per image), although well-behaved TIFF files will read somewhat faster than with the default setting.

The root cause of this problem is unclear. Such files read OK on Windows, but not on Mac. One workaround is to use Photoshop or some other image editing tool to remove the profile entirely, or to assign or convert the profile to sRGB (“sRGB IEC61966-2.1”), which appears to be an equivalent profile with a different name. TIFF files with the Nikon profile are read correctly.

Selecting the native Look & Feel, while running with the Ubuntu Studio theme, causes several problems ranging from improper screen format to red “Uh-oh” exceptions. This appears to be due to problems in the Java runtime system, specific to the Ubuntu Studio look & feel.

The workaround is to select “Java cross-platform Look & Feel” at Options > Preferences > Look & Feel.

On 32-bit systems, large TIFF files may provoke a bug in the Java runtime system that is diagnosed like this:

          Trying to read <filename>
          Exception occurred during event dispatching:
          java.lang.OutOfMemoryError
               at java.io.RandomAccessFile.readBytes(Native Method)

The threshold for “large” depends on circumstances. Most often it is around 70 MB, but even much shorter files can cause problems on some systems and workflows.

If you encounter this error, go to Options > Preferences > Preprocessing and place a checkmark to select “Use External TIFF Reader”. This uses a different method of image reading that bypasses the Java runtime bug.

Recent versions (T201108020545 and later) automatically fall back to Use External TIFF Reader if this bug is encountered.

On some systems, the following error occasionally occurs during retouching:

  java.awt.image.RasterFormatException: negative width

The problem seems to be related to both the computer system and to the style of retouching. This problem is believed to be fixed in releases at level T201009091815 and beyond.

This problem is believed to be fixed as of version 1.02 build T201008081620. Please let us know if you encounter it again!

As a workaround in earlier versions, simply turn down the setting for graphics acceleration on your video card. On Windows XP, the recipe is Start > Control Panel > Display > Settings > Advanced > Troubleshoot tab > Hardware acceleration, move slider and Apply. At a setting of None, the brush should move smoothly, with several updates per second even when the brush is a hundred pixels across. Try that so you can see how it works, then select the highest setting that works that well or better.

(This problem is believed to be fixed. Please let us know if it reappears.)

The symptom here is that in retouching mode the brush does not appear. The underlying problem is that the brush width has gotten insanely large, probably due to an accidental turn of the mousewheel or the equivalent swipe on a touchpad. (Most users experiencing this problem are on Macs with touch input.) The brush width sticks from one run to another, so once the brush disappears it stays disappeared until the problem is fixed.

Most instances of this problem are automatically fixed by downloading and installing the latest version of the software from http://zerenesystems.com/cms/stacker/softwaredownloads.

In a few remaining cases, it is necessary to manually edit the “zerenstk.cfg” configuration file so as to delete the line that begins with “RetouchingBrush.Width=”. This file is located in the ZereneStacker folder as described HERE in the FAQ. This file can be edited with any plain text editor, such as Notepad on Windows or TextEdit on Macs. The offending line probably says something like “RetouchingBrush.Width=Infinity”. Get rid of that line entirely. Edit the file while Zerene Stacker is not running, and then Zerene Stacker should behave normally when launched again.

(This problem is fixed in Build T201303132055 and later.)

The external TIFF reader erroneously truncates the file name or path at the first comma. This error results in a generic “Uh-oh – something went wrong” popup, with diagnostic details in the console log that go something like this:

          Trying to read /Users/zstest/ImageFiles/stuff, etc./TIFF/IMG_2575.tif
          ...
          From external converter error stream: TIFFOpen: /Users/zstest/ImageFiles/stuff: Cannot open.
          com.zerenesystems.stacker.a.o: Tried but failed to read /Users/zstest/ImageFiles/stuff, etc./TIFF/IMG_2575.tif using external converter.

Notice the truncation of “ImageFiles/stuff, etc./TIFF/IMG_2575.tif” to be just “ImageFiles/stuff” in the error message.

There are two different ways to avoid this problem:

1. Rename the files or folders to remove the commas, or

2. Go to Options > Preferences > Preprocessing and remove the checkmark on “Use External TIFF Reader”. This will cause Zerene Stacker to use its internal TIFF reader, which is a completely different piece of software that handles commas correctly.

This extraordinarily puzzling problem, reported on four systems to date, has the symptom that a downloaded bundle runs fine once, but on subsequent launches it aborts immediately with “The application ZereneStacker quit unexpectedly” even though there is no problem with memory allocation.

The root cause of this problem turns out to be that the Mac operating system has somehow modified or replaced a JavaApplicationStub that is provided with the bundle. The modification/replacement happens on first execution, which is why Zerene Stacker works once but not after that.

As of Build T201410311610 (October 31, 2017), Zerene Stacker has used a different launch procedure that avoids this problem.

The earlier short-term solution was to replace the JavaApplicationStub in Zerene Stacker with one that should already be found on your system. Here is that procedure:

The file to be replaced is at ZereneStacker.app/Contents/MacOS/JavaApplicationStub . To reach into this directory, simply right-click (or ctrl-click) on the ZereneStacker icon, then select Show Package Contents. Navigate to Contents/MacOS, and you will see the file JavaApplicationStub.

The JavaApplicationStub that you need to use instead can be accessed using Finder. Open a Finder window and go to <bootdisk>/System/Library/Frameworks/JavaVM.framework/Resources/MacOS, where <bootdisk> is just the name of the disk that you boot from. There you will see one or two files, JavaApplicationStub and possibly JavaApplicationStub64.

Right-click on the JavaApplicationStub in the …Frameworks… tree, and select Copy “JavaApplicationStub”.

Then go into Contents/MacOS of the ZereneStacker package, right-click on any blank space, and select Paste Item. You should receive a warning that “JavaApplicationStub” already exists. Go ahead and allow the replacement, after looking one more time to be sure that you really are inside the ZereneStacker package and not still in Frameworks.

When using the Capture One™ raw converter from Phase One, sometimes a red “Uh-oh” popup error will occur, with a detailed diagnostic that says this:

      java.awt.color.CMMException: LCMS error 13: couldn't link the profiles

To solve this problem, go into Capture One and change its settings so as to select a color profile other than “Embed Camera Profile”, before generating TIFF or JPEG files to be loaded into Zerene Stacker. The “Embed Camera Profile” option apparently causes Capture One to produce an output file that contains multiple color profiles, linked together in some way that cannot be handled by the image I/O libraries used inside Zerene Stacker. With “Embed Camera Profile” not selected, Capture One will include only the image's own color profile, which is fully supported by Zerene Stacker.

This problem is believed solved in Build T201610272136 and later.