What does Windows error code 2021 (ERROR_COLORSPACE_MISMATCH) mean?

Status / error code:		Category:

Constant name:
Source:		Operating System:
Description: The selected transform does not accept the bitmap color space or channel layout.

Previous	Next
ERROR_INVALID_TRANSFORM	ERROR_INVALID_COLORINDEX

ERROR_COLORSPACE_MISMATCH

The transform does not match the bitmap color space.

ERROR_COLORSPACE_MISMATCH is Win32 error 2021 (0x7E5). A transform has defined source and destination spaces, while bitmap translation also declares concrete BMFORMAT values, channel counts, and strides. The failure means those contracts disagree even if the transform and bitmap buffers are individually well formed.

Frequent mismatches

RGB bytes are passed through a transform whose source profile describes CMYK, gray, Lab, or named colors
the application chooses a BMFORMAT that does not match actual channel order, depth, or alpha layout
source and destination profiles were reversed when the transform was constructed
a proofing or device-link transform is reused for an unrelated preview or export stage
cached transform metadata is stale after the document color model or destination device changes

Evidence from both sides

Record the transform’s profile chain and declared source/destination signatures, bitmap format, width, height, input and output stride, channel count, alpha handling, rendering intent, and the operation direction. Hash profiles and log bounded header metadata; do not capture image pixels in routine telemetry.

Diagnostic sequence

Derive the bitmap format from the decoder or image metadata rather than a UI label. Compare it with the transform’s first profile and the documented BMFORMAT layout. Test a one-pixel or small known-color buffer to remove stride and allocation noise.

Recreate the transform with source and destination profiles in the intended order. Then verify input and output formats separately. A transform that accepts TranslateColors with compatible COLORTYPE values but rejects the bitmap path usually points to bitmap format or stride selection.

Correction and validation

Select a transform built for the actual source space, or explicitly convert the bitmap into the transform’s expected intermediate format. Recompute caches whenever document mode, profile, rendering intent, or destination changes.

Developers should keep typed color-space metadata beside pixel buffers and reject implicit RGB assumptions. Validate round-trip test colors and out-of-gamut behavior after the error is fixed; mere API success does not guarantee correct color appearance.

Difference from ERROR_INVALID_COLORSPACE

ERROR_INVALID_COLORSPACE means a space declaration or combination is itself invalid. Error 2021 is relational: the transform and bitmap describe different otherwise recognizable spaces.

Example

A scanner produces 16-bit gray samples, but the preview cache reuses an sRGB monitor transform and labels the input BM_RGBTRIPLETS. Translation returns 2021. Building a gray-to-monitor transform and using the matching bitmap format resolves the contract.

References

Looking for a different code? Search another status or error code.