---
Product: psd
Platform: java
Page Type: kb
Canonical URL: https://kb.aspose.org/psd/java/troubleshooting
Last Updated: 2026-11-19
---

# Troubleshooting Aspose.PSD FOSS for Java

Diagnose and fix common problems loading, inspecting and saving PSD and PSB documents with Aspose.PSD FOSS for Java: load exceptions, unsupported setters, layer names and opacity mistakes.

## Overview

This page covers the problems you are most likely to meet when you load, inspect and save PSD and PSB documents with Aspose.PSD FOSS for Java.

---

### Loading Problems

#### `PsdLoadException`: Invalid PSD signature

The data does not start with the PSD signature `8BPS`. Check that the file is a real PSD or PSB file and that it was not changed by a transfer. Loading from a path gives a `RuntimeException` whose cause is the `PsdLoadException`.

#### `PsdLoadException`: unexpected end of data, or a section longer than the remaining data

The stream is empty, or the file is cut off before the end of its image resources or layer sections, for example by an interrupted download. Get a complete copy of the file. A file that is cut off later, inside the merged image data at the end, still loads, so a successful load does not prove that a file is complete.

#### `FileNotFoundException`

The path does not exist. Check the path and the working directory of your program.

#### `IllegalArgumentException` when loading

The path you passed is `null`.

#### A `catch (IOException)` block does not catch the load error

`PsdLoadException` extends `Exception`, not `IOException`. Catch it as well.

---

### Editing and Saving Problems

#### `UnsupportedOperationException` from a setter

You called one of the seven setters that this edition does not support: `PsdImage.setActiveLayer`, `setImageResources`, `setGlobalLayerResources`, `setHasTransparencyData`, or `Layer.setChannelInformation`, `setLayerMaskData`, `setLayerBlendingRangesData`. Leave that data as loaded and edit layer name, visibility or opacity instead.

#### Opacity prints as a negative number

`Layer.getOpacity()` returns a signed `byte`. Use `getOpacity() & 0xFF` for the value from 0 to 255.

#### The layer count changes after `setLayers`

Removing or reordering layers through `setLayers` is not a supported edit. Keep the array that `getLayers()` returned.

#### Layer names contain `?` after saving

Layer names are written as ASCII text. A character that is not ASCII is saved as `?`, and saving an edited document rewrites every layer name. Keep layer names ASCII, or do not edit the document.

#### `RuntimeException` caused by `PsdSaveException` when saving

A layer name is longer than 255 characters. `save` declares only `IOException`, so the save error arrives as a `RuntimeException`; read `getCause()`.

#### The output stream is closed after `save`

`PsdImage.save(OutputStream)` closes the stream that you pass in. Do not pass a stream that you still need.

---

### Environment Problems

#### `NoClassDefFoundError` for `java.awt.Color` when loading an indexed-color file

The runtime has no `java.desktop` module, for example a minimal runtime image. Indexed-color documents need it; RGB, CMYK and PSB files loaded without it in a test. Use a runtime that includes `java.desktop`.

#### `UnsupportedClassVersionError`

The library is compiled for Java 11. Run it on Java 11 or later.

## See Also

- [Aspose.PSD for Java — Enterprise Knowledge Base](https://kb.aspose.com/psd/java/)