Resolving Ignition 8.3 Image Folder Rename Errors (IGN-14057)

On Ignition 8.3, renaming any folder in Image Management fails with java.lang.IllegalArgumentException. The failure is not tied to one folder or to the characters in the new name. It is a gateway-side defect tracked as IGN-14057. A similar rename failure was reported in an earlier release, so treat this as a regression in 8.3.

Until a build with the fix is installed, the working path is: download the images, create a folder under the new name, re-upload the images, repoint component references, then delete the old folder. The sections below follow that order. Each one ends with the check that must pass before you move on.

IGN-14057 failure signature in Image Management

Capture the full error before you change anything. That way you can confirm you are dealing with this defect and not a permissions or naming problem.

1. In the Designer, open Image Management and attempt the folder rename again.
2. When the error dialog appears, open the Details tab and copy the full stack trace.
3. Repeat the rename on a second, unrelated folder. The new name should use only letters, digits, and underscores.

The trace matches this defect when it contains these frames, in this order from the top:

java.lang.IllegalArgumentException
  at com.google.common.base.Preconditions.checkArgument(Preconditions.java:129)
  at com.inductiveautomation.ignition.common.resourcecollection.LastModification.update(LastModification.java:30)
  at com.inductiveautomation.ignition.gateway.images.ImageManagerImpl.lambda$copyImage$3(ImageManagerImpl.java:212)
  ...
  at com.inductiveautomation.ignition.gateway.images.ImageManagerImpl.copyImage(ImageManagerImpl.java:214)
  at com.inductiveautomation.ignition.gateway.images.ImageRpcImpl.renameImageFolder(ImageRpcImpl.java:117)

Check before continuing: the second folder fails with the same frames. If it renames cleanly, you have a folder-specific problem, not IGN-14057.

Rename call path through the gateway resource collection

The Designer does not rename the folder itself. It makes an RPC call to the gateway, visible in the trace as RpcRoutes.handle and RpcDelegate$DelegateRpcHandler.handle running under the gateway's Jetty servlet stack. The gateway handler ImageRpcImpl.renameImageFolder does not perform an in-place directory move. It calls ImageManagerImpl.copyImage, which streams over the images in the folder and builds a new copy of each one at the new path.

In 8.3, images live in the gateway's resource collection. Every resource carries last-modification metadata, which the copy step updates through LastModification.update. That method guards its input with Guava's Preconditions.checkArgument. When the boolean precondition evaluates false, Guava throws IllegalArgumentException, and here it throws with no message. The stream ends in a toList() call, so the exception leaves copyImage before any copy list reaches the rename handler, and the whole operation aborts.

This has three practical consequences:

• The folder name is never the problem. The exception comes from metadata handling on the copied images, not from name validation.
• Restarting or reinstalling the Designer changes nothing. The failing code runs in the gateway.
• Any operation that routes through copyImage can fail the same way. Test a single-image move on a scratch image before relying on it as a shortcut.

Check before continuing: refresh the Image Management tree. The original folder should be present with its full image count, and there should be no partial folder under the new name. If a stray target folder exists, note its contents and delete it before proceeding.

Image inventory, references, and backup

Every image path includes the folder name. Moving images to a new folder breaks every component that points at the old path. Collect all of the following before touching the images.

1. Image list. Record every file in the folder, including subfolders, with exact file names and extensions. Case matters in path strings.
2. References. In the Designer, run Find/Replace for the old folder name across the projects on the gateway. Record each view, window, template, or script that contains the path. Include expression bindings and scripts that build image paths by string concatenation; a literal search can miss these.
3. Inheritance. Note any parent or inherited projects. A reference in a parent project affects every child project.
4. Gateway backup. Take a gateway backup and store it off the gateway. The procedure deletes a folder, and the backup is your rollback.

Check before continuing: the backup file exists off-box, and you have an image count and a reference list you can check off later.

Image export from the source folder

Download the images from the folder you want to rename using Image Management's download function.

1. Select the images in the source folder and download them to a local working directory. Handle each subfolder separately so the structure is preserved.
2. Keep the original file names unchanged. Renaming files at this stage adds a second reference change on top of the folder change.
3. Open a sample of the downloaded files, including the largest and any SVGs, to confirm they are complete and not truncated.

Check before continuing: the number of files in the local directory, per subfolder, matches the inventory from the previous step. Do not proceed on a short count.

Target folder creation and re-upload

You can delete the old folder first and then create the new one. The safer order is to create the new folder first, populate it, and delete the old folder only after the new one is proven. Both folders exist briefly, so there is no gap where components show missing images.

1. In Image Management, create a new folder with the target name. Folder creation does not go through renameImageFolder, so this step succeeds on an affected gateway.
2. Recreate any subfolders under the new folder to mirror the original structure.
3. Upload the downloaded images into the matching folders.
4. Refresh the Image Management tree and preview several images in the new folder.

Check before continuing: the new folder shows the same file count, names, and subfolder layout as the inventory, and the previews render. The old folder is still untouched at this point.

Component references to the old folder path

With both folders present, move references to the new path while the old images still resolve as a fallback.

1. Use Designer Find/Replace to change the old folder segment of the path to the new one. Scope the search to the full folder segment, including the path separators on both sides. Otherwise a short folder name can match inside unrelated strings.
2. Hand-edit the dynamic references recorded during inventory, such as expressions and scripts that build paths. Find/Replace will not always catch these.
3. Save and publish the affected projects.
4. Run a second Find/Replace search for the old folder name.

Check before continuing: the second search returns zero hits, apart from any you have deliberately kept and documented. Every entry on the reference list is checked off.

Fix tracking for IGN-14057

This procedure is a workaround. The underlying rename remains broken on affected 8.3 builds until the gateway is upgraded.

• Search the Ignition release notes for IGN-14057 before each planned upgrade. Only a release whose notes list that ticket as fixed should be expected to rename folders in place.
• After upgrading, test the rename on a scratch folder holding one or two throwaway images before renaming a production folder.
• If the scratch rename still throws, capture the Details trace and report it to Inductive Automation support, quoting the ticket number. A different top frame means you have a different defect.
• Until the fix is confirmed, route every image-folder rename on the gateway through the export / recreate procedure. Do not retry the rename on production folders.

Old folder removal and end-to-end check

Remove the original folder only after the new folder and all references have passed their checks. Then confirm the running system, not just the Designer.

1. Prerequisite: the reference search returns zero hits and the new folder count matches the inventory. If either fails, stop here.
2. Delete the old folder in Image Management and refresh the tree. Confirm the new folder is unaffected.
3. Check the gateway logs for new image-related errors raised during or after the delete.
4. Open each Perspective view and Vision window from the reference list in a live client, not only in the Designer preview, and confirm every image renders. Missing images typically show as a blank area or a broken-image placeholder.
5. Force a full client refresh, such as a session reload or client restart, and repeat the check. Cached images can hide a broken path until the cache clears.
6. Walk the screens that build image paths dynamically through the states that select each image, so every computed path is actually requested.
7. Confirm the new folder name and complete image set appear in Image Management on the gateway. Record the change against the backup taken before the work, so you can roll back to that backup if a missed reference turns up later.

FAQ