Known Issues is a list of unusual problems that have been reported typically one to three times, but may be seen by other people too.
If you encounter difficulties that are not on this list, or if the suggested workarounds do not work for you, then please contact firstname.lastname@example.org. We try hard to fix problems, but we have to know about them first!
Here is an index to the known issues:
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 also solved in the current beta release of Zerene Stacker.
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 email@example.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 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. Be careful that you do not remove other folders in ~/Library/Preferences, as 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)
On Windows and Mac, 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.
(This problem is believed to be fixed. Please let us know if it reappears.)
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.
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.
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 megabytes per 1 megapixel, so for example 3600 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 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:
On Windows, if the problem is caused by an indexing plugin, then one way to work around the problem is this:
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.
(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.
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 firstname.lastname@example.org 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 email@example.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.
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 firstname.lastname@example.org .
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.
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.
In the long term, we will change the Zerene Stacker bundle to use a different first-execution procedure to avoid this problem.
But as a short-term workaround, it has proved adequate to replace the JavaApplicationStub in Zerene Stacker with one that should already be found on your system. Here is the 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.
Note: In all recent versions, you can drag-and-drop directly onto the input files list. There is no need to File > Add Files to open a filechooser as described below. Just open a separate Finder window, select your image files there, then use drag-and-drop to enter them directly into Zerene Stacker's “Input Files” panel, at the place where it says ”(Drop files or folders here to begin)”.
Further explanation and other approaches follow.
The Java filechooser currently used by Zerene Stacker does not display alternate volumes like the native Mac filechooser does. External drives can still be accessed, but the procedure is somewhat awkward.
On OS X 10.5 (Leopard) and later, the easiest approach is to open a filechooser dialog box in Zerene Stacker, using File > Add Files. Then separately, use Finder to open the external drive or network share, go to the appropriate directory, and select the files of interest. Drag and drop those files onto the Add Files dialog of Zerene Stacker, then click the Add button in the Zerene Stacker dialog. This method also has the advantage of showing you a thumbnail preview of the files to be added.
Alternatively (and required for OS X 10.4), you can go to the bar at the top of the window, the one where the current directory is shown. Click once on that bar and it will expand into a pull-down list of enclosing directories. At the bottom of the list will be an entry like “Macintosh HD”, representing the main file system of the computer. Click that. Scroll to the bottom of the list and double-click on Volumes. That should give you a list of all your currently mounted media. Double-click on any external drive to open that, then navigate as usual.
The latter approach is required on OS X 10.4 because drag-and-drop into the Zerene Stacker filechooser does not work on that system.
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.