Troubleshooting Aspose.PSD FOSS for .NET

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

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
{
    using var image = PsdImage.Load("input.psd");
}
catch (PsdLoadException ex)
{
    Console.WriteLine($"Not a valid PSD/PSB file: {ex.Message}");
}

`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.Length > 255 ? layer.Name[..255] : layer.Name;
image.Save("output.psd");

Editing Problems

`NotSupportedException` when setting a property

Several properties are read-only in this FOSS build. On PsdImage: ActiveLayer, ImageResources, GlobalLayerResources, HasTransparencyData. On Layer: ChannelInformation, LayerMaskData, LayerBlendingRangesData. Treat these as get-only — do not assign to them.

Layer opacity looks wrong after setting it

Layer.Opacity is a byte in the 0-255 range, 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 array elements can’t simply be removed in place — reassign the whole filtered array:

image.Layers = image.Layers.Where(l => l.Name != "Unwanted Layer").ToArray();

Installation Problems

Package not found

Confirm the exact package identity:

git clone https://github.com/aspose-psd-foss/Aspose.PSD-FOSS-for-.NET.git
cd Aspose.PSD-FOSS-for-.NET
dotnet build

Diagnostic Checklist

Before opening a support issue, run through this checklist:

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

Troubleshooting Aspose.PSD FOSS for .NET