Aspose.PSD FOSS
Python
Troubleshooting Aspose.PSD FOSS for Python

Troubleshooting Aspose.PSD FOSS for Python

Troubleshooting Aspose.PSD FOSS for Python

This page covers the most common problems encountered when loading, inspecting, and saving PSD/PSB documents with Aspose.PSD FOSS for Python.

Loading Problems

PsdLoadException with a message about an unsupported version

The file’s declared PSD version field is neither the standard PSD nor the large-document PSB value. Confirm the file is a genuine, uncorrupted PSD/PSB document before loading:

try:
    image = PsdImage.load("input.psd")
except PsdLoadException as ex:
    print(f"Not a valid PSD/PSB file: {ex}")

PsdLoadException about a section length exceeding a boundary

The file’s internal length fields are inconsistent with its actual size — this usually means the file is truncated or corrupted, not that it uses an unsupported but otherwise valid structure. Re-export the file from its source application and retry.

Saving Problems

PsdSaveException about a Pascal string length

A string value — most commonly a layer or resource name — exceeds 255 bytes, the maximum a PSD Pascal string field can encode:

layer.name = layer.name[:255] if len(layer.name) > 255 else layer.name
image.save("output.psd")

Editing Problems

NotSupportedException when setting a property

Several properties are read-only in this FOSS build. On PsdImage: active_layer, image_resources, global_layer_resources, has_transparency_data. On Layer: channel_information, layer_mask_data, layer_blending_ranges_data. Treat these as get-only — do not assign to them.

Layer opacity looks wrong after setting it

Layer.opacity is conventionally a 0-255 value, not a 0.0-1.0 fraction or a percentage:

layer.opacity = 200  # approximately 78% opaque, not 200%

A layer removal doesn’t take effect

PsdImage.layers has a working setter at the collection level, but individual list elements can’t simply be removed in place — reassign the whole filtered list:

image.layers = [l for l in image.layers if l.name != "Unwanted Layer"]

Installation Problems

Package not found

Confirm the exact package identity:

git clone https://github.com/aspose-psd-foss/Aspose.PSD-FOSS-for-Python.git
cd Aspose.PSD-FOSS-for-Python
# No packaging manifest is published yet -- run from this folder,
# or add it to PYTHONPATH:
export PYTHONPATH=$PWD:$PYTHONPATH

Diagnostic Checklist

Before opening a support issue, run through this checklist:

  1. Confirm the file is genuinely PSD/PSB — a PsdLoadException about an unsupported version usually means the file isn’t a real PSD/PSB document.
  2. Check for NotSupportedException — you may be setting one of the 7 read-only properties listed above instead of reading it.
  3. Verify opacity is in the 0-255 range, not 0.0-1.0 or 0-100.
  4. Keep string values under 255 bytes before saving, to avoid PsdSaveException.
  5. Call image.save after every edit — changes to a Layer instance are not persisted until the document is saved.

See Also