> Markdown version of https://docs.laavat.io/appendixes/error-codes/ from the LAAVAT PKI and Signing Platform documentation. All pages: https://docs.laavat.io/llms.txt

# Signing error codes

When a signing or encryption request cannot be completed, it ends in state
`Failed` (64) and `GET /imagesignings/{id}` returns an `errorStatus` that
names the cause. This page lists the codes and what to do about each.

Most codes come from the signing tool that processes your upload: RAUC,
mkimage, bootgen, SPSDK, imgtool, NXP CST, osslsigncode or jarsigner. When the
tool refuses the input, the platform reports the matching code in
`errorStatus` and the tool's own message in `errorDetail`, with server paths
and key references removed. A tool failure that matches no code is reported
with the tool's generic `...SigningFailed` code, and `errorDetail` then carries
the tool's last message.

The platform also checks the upload and `request.json` before any tool runs,
and refuses some inputs that the tool would sign but that the device could not
use. These codes carry the platform's own message in `errorDetail`, naming the
file, field or node. A failure on the platform's side has no `errorDetail`;
LAAVAT Support traces it by the request ID.

The `signing-tool` client shows the code in `imagesigning get` output, and the
GUI shows the request as Failed. The example messages below are what the tool
or the platform printed when the case was reproduced; the actual message names
your file.

This page covers signing and encryption requests. Certificate issuance and CA
codes such as `caExpired`, `dnHasBeenUsedBefore` and
`publicKeyHasBeenUsedBefore` are not listed here.

## Codes shared by all operations

| Code | Cause | Fix |
| --- | --- | --- |
| `defaultErrorStatus` | A failure with no documented code | Contact LAAVAT Support with the request ID |
| `keyNotFound` | The operation's key is not in the HSM | Contact LAAVAT Support |
| `payloadIsNotBase64Encoded` | The uploaded payload is not Base64 | Upload the file Base64 encoded, as the client does |
| `multiPayloadNotSupported` | `payloads[]` was used on an operation that signs one payload per request; only OP-TEE signing, detached signature, digest signing, Windows binary signing and JAR signing accept several | Send one request per file |

## Codes for the upload and request.json

The platform checks these before any signing tool runs. `errorDetail` names the
file or field.

| Code | Cause | Example message | Fix |
| --- | --- | --- | --- |
| `requestArchiveInvalid` | SPSDK, Windows binary and JAR signing: the upload is not a zip, tar or tar.gz archive. RAUC reports this case as `raucBundleInvalid`. For SPSDK signing, also an archive member in a subdirectory: `./name` members, as `tar -C dir .` writes them, count as top-level files | `the upload is not a zip, tar or tar.gz archive`; `archive member "cfg/sign.yaml" is not at the top level; pack the files flat` | Pack the files flat in a zip, tar or tar.gz |
| `requestJsonInvalid` | `request.json` is missing from the archive, empty or not valid JSON; a field the operation needs is missing; or a field has the wrong type or a value the operation does not take | `request.json is missing from the archive`; `request.json: image is missing` | Fix `request.json` as `errorDetail` says |
| `requestFileMissing` | `request.json` names a file that is not in the archive: a `binaryFilename` (HAB), a bootgen partition file, the SPSDK configuration, a `fileName` (Windows, JAR) | `sign.yaml (request.json config) is not in the archive`; `csfs[spl]: binaryFilename nothere.bin is not in the archive` | Add the file or fix its name (case-sensitive) |

## Digest signing

| Code | Cause | Fix |
| --- | --- | --- |
| `unknownHashAlgorithm` | The request names a hash algorithm the operation does not support | Use one of the hash algorithms listed for the operation in the API description |
| `invalidDigestSize` | The digest length does not match the request's hash algorithm, for example a SHA-512 digest sent with the SHA256 option | Send the digest the chosen algorithm produces |
| `unsupportedSignaturePadding` | The request asks for a signature padding the key type does not support | Use the padding the operation lists for its key type |
| `UnknownProtectionType` | The operation's key information names a protection type the platform does not know; a fault of the key setup, not of the request | Contact LAAVAT Support with the request ID |

The CMS codes `invalidCMSCertificates`, `invalidCMSSettings`, `emptyCMSTree`
and `keyNotSuitableForSigning` are described with the settings that cause them
in [Digest signing › Errors](https://docs.laavat.io/usage/signing-encryption/digest-signing/#errors).

AES encryption has one code of its own, `aesGcmPayloadTooLarge`, described in
[AES image encryption](https://docs.laavat.io/usage/signing-encryption/aes-encryption/#gcm-modes-aes-gcm-aes-gcm-pskek).

## RAUC bundle signing

`RaucBundleSigning`, `RaucBundleSigningWithOneTimeKey` — RAUC 1.15.

| Code | Cause | Example message | Fix |
| --- | --- | --- | --- |
| `raucImageTypeUnknown` | An `[image.*]` section has no `type=` and the file name extension maps to no image type, or `type=` is unsupported | `Cannot parse [image.rootfs]: No 'type=' set and unable to map extension of file 'rootfs' to known image type` | Give the image a known extension (`.img`, `.ext4`, `.vfat`, `.squashfs`, `.ubifs`, `.tar.*`) or set `type=` |
| `raucManifestInvalid` | `manifest.raucm` is missing, has an unknown key or section, a malformed value, a `min-rauc-version` newer than the platform's RAUC, or the crypt recipient certificates cannot be loaded | `Invalid key 'bogus' in group '[image.rootfs]'`; `Minimum RAUC version in manifest (9.9) is newer than current version (1.15.2)` | Fix the manifest against the platform's RAUC version |
| `raucImageFileMissing` | The manifest names an image or hook file that is not in the bundle content | `image file 'rootfs.img' for slot 'rootfs' does not exist in bundle content dir` | Add the file or fix the `filename=` entry |
| `raucBundleInvalid` | The input of a re-sign is not a RAUC bundle; the upload of `RaucBundleSigningWithOneTimeKey` is not a zip, tar or tar.gz archive, or is truncated; or the content holds symlinks, hidden directories or special files | `Invalid bundle format: Signature size (...) exceeds bundle size`; `absolute symlinks are not supported as bundle contents (evil)` | Upload a bundle built by `rauc bundle`, or plain files only |
| `raucFormatMismatch` | The `format` in `request.json` differs from `format=` in the manifest's `[bundle]` section (a manifest without `format=` is `plain`). A request without `format` takes the manifest's, except `crypt`, which `request.json` must ask for | `request.json format plain does not match the manifest's format verity`; `request.json has no format, but the manifest's format is crypt; set format crypt` | Make both say `plain`, `verity` or `crypt` |
| `raucSigningFailed` | RAUC failed for another reason | — | Contact LAAVAT Support with the request ID |

See [RAUC bundle signing](https://docs.laavat.io/usage/signing-encryption/raucsigning/).

## FIT image signing (U-Boot, kernel)

`SignUBoot`, `SignKernel` — mkimage from U-Boot 2026.04.

| Code | Cause | Example message | Fix |
| --- | --- | --- | --- |
| `fitNotFdt` | The upload is not a flattened device tree | `Invalid FIT blob` | Upload the `.itb` as `mkimage -f` produced it |
| `fitFdtInvalid` | The FIT cannot be signed as built: a signature node with an unsupported `algo`, an image without a hash node, a configuration whose `sign-images` covers nothing, or a reference to a missing image | `Unsupported signature algorithm (md5,rsa2048) for 'signature-1' signature node in 'conf-1' image node`; `Failed to find any hash nodes in configuration 'conf-1/signature-1' image 'kernel'` | Fix the `.its` and rebuild the FIT |
| `fitNoSignatureNodes` | No configuration has a signature node, so there is nothing to sign | — | Add a `signature-1` node with `key-name-hint` to the configurations to sign |
| `fitUnitAddresses` | A node name contains a unit address (`@`, for example `kernel@1`). mkimage signs such a FIT, but U-Boot with signature checking refuses it at boot | `node images/kernel@1 has a unit address (@), which U-Boot refuses to verify; use names like kernel-1 and conf-1` | Rename the nodes to the `kernel-1`, `conf-1` style |
| `fitAlgorithmMismatch` | The `algo` of a signature node does not match the product key: another RSA size, or ECDSA declared for an RSA key or the other way round | `configurations/conf-1/signature-1: algo sha512,rsa4096 does not match the product key, RSA-2048` | Declare the hash with the type and size of the product's key, for example `sha256,rsa2048` |
| `fitCipherNotSupported` | An image has a `cipher` node, which asks for encryption. The platform signs FIT images but does not encrypt them | `image kernel has a cipher node; encrypted FIT images are not supported` | Remove the `cipher` node, or encrypt the image before it goes into the FIT |
| `fitSigningFailed` | mkimage failed for another reason | — | Contact LAAVAT Support with the request ID |

See [FIT image signing](https://docs.laavat.io/usage/signing-encryption/fitsigning/).

## Xilinx boot image signing

`SignBootgenImage`, `SignAndEncryptBootgenImage` — bootgen 2025.2.

| Code | Cause | Example message | Fix |
| --- | --- | --- | --- |
| `bootgenInputFileUnreadable` | bootgen cannot read a file of the upload: it is empty or not of the declared kind. A file that is missing from the upload gives `requestFileMissing` | `Cannot read file - empty.elf` | Upload the build outputs unmodified |
| `bootgenInputFileInvalid` | A partition file cannot be parsed: an ELF with a wrong header, a PMU firmware that is not a 32-bit MicroBlaze ELF, a `.bit` that is not a Vivado bitstream | `ELF Parsing Error !!! Wrong Header Size`; `Bitstream parsing error !!! Unsupported BIT file` | Upload the build outputs unmodified |
| `bootgenPartitionTooLarge` | A partition does not fit its destination: TCM, PMU RAM (128 KB) or the 32-bit address space | `has exceeded TCM and cannot be loaded by FSBL.` | Shrink or relink the image |
| `bootgenBifSyntax` | An attribute name or value, or a file name, that the boot image description does not accept | `Parsing problem at badattr.bif:1.162-164` | Use documented attribute values and plain file names without spaces |
| `bootgenAttributeInvalid` | An attribute combination bootgen rejects: two `bootloader` items, attributes a partition does not take, `checksum` with authentication, the FSBL on a CPU other than `a53-0`/`r5-0`, an `offset` or `alignment` that is not a multiple of 64, `ppk_select` or `spk_id` out of range | `BIF attribute error !!! A bootimage cannot have more than one bootloader.`; `Offset (0x33) is not a multiple of 64`; `'ppk_select' can either be 0 or 1` | Fix the attributes in `request.json` |
| `bootgenSigningFailed` | bootgen failed for another reason | — | Contact LAAVAT Support with the request ID |

See [Xilinx boot image signing](https://docs.laavat.io/usage/signing-encryption/xilinxsigning/).

## AHAB signing with SPSDK (i.MX93)

`SignSPSDK` — SPSDK 3.11 `nxpimage`.

| Code | Cause | Example message | Fix |
| --- | --- | --- | --- |
| `ahabConfigUnreadable` | The configuration in the upload is not valid YAML or JSON, a value is out of range (`family`, `revision`, `fuse_version`, `sw_version`, `fast_boot`), or it has a key the platform does not support, for example `blob`, `certificate`, `signer_#2` or a misspelt key. `errorDetail` names the key and its line | `mimx9352-sign.yaml: fuse_version must be a number (line 7, column 15)`; `Requested revision z9 is not supported.`; `sign.yaml: blob is not an ahab sign option the platform supports (line 7, column 1)` | Keep only the fields listed in [The SPSDK configuration file](https://docs.laavat.io/usage/signing-encryption/spsdksigning/#the-spsdk-configuration-file) |
| `ahabImageNotContainer` | The image is not a complete i.MX93 boot image for the memory type: not an imx-boot image, truncated or corrupt | `The image parsing failed. The image is not matching any of memory types.` | Upload the whole `imx-boot` file from imx-mkimage, unmodified |
| `ahabMemTypeUnsupported` | `memType` names a memory type the device does not boot an AHAB image from | `Memory type not supported: Flexspi NAND` | Leave `memType` out or use one SPSDK supports for the family |
| `ahabSigningFailed` | SPSDK failed for another reason | — | Contact LAAVAT Support with the request ID |

The platform does not check `family` against the image, because an AHAB
container carries no chip ID. A request with the family of another chip, for
example `mimx8ulp` for an i.MX93 image, is signed, and the result does not boot.

See [SPSDK signing](https://docs.laavat.io/usage/signing-encryption/spsdksigning/).

## MCUboot image signing

`SignMcuBoot`, `EncryptMcuBoot` — imgtool.

| Code | Cause | Example message | Fix |
| --- | --- | --- | --- |
| `mcubootHeaderNotZeroed` | `pad_header` is false but the image does not start with `header_size` zero bytes. An already signed image gives this code with `pad_header` false, and `mcubootImageTooLarge` with `pad_header` true when the second header no longer fits `slot_size` | `Header padding was not requested and image does not start with zeros` | Set `pad_header: true` for a `.bin` without reserved header space, or upload the unsigned image |
| `mcubootImageTooLarge` | The image plus its TLVs and trailer does not fit in `slot_size` | `Image size (0x2297) + trailer (0x630) exceeds requested size 0x1000` | Check `slot_size` against the partition or make the image smaller |
| `mcubootVersionInvalid` | `version` is not `major.minor.revision+build` or a part is too large; `security_counter` is not `auto` or a 32-bit integer | `Invalid version number, should be maj.min.rev+build with later parts optional` | Fix the version fields |
| `mcubootHexInvalid` | A `.hex` input is not valid Intel HEX, or no load address is available for the requested output | `Hex file contains invalid record at line 1`; `No address exists in input file neither was it provided by user` | Upload a valid `.hex`, or a `.bin` with `load_addr` |
| `mcubootOptionInvalid` | An option imgtool rejects: `header_size` below 32, `align` not one of 1, 2, 4, 8, 16, 32, or a `slot_size` of 0 | `Minimum value for -H/--header-size is 32`; `Invalid value for '--align': '3' is not one of '1', '2', '4', '8', '16', '32'.`; `images[0]: slot_size 0 must be larger than the signed image` | Take the values from the board's bootloader configuration |
| `mcubootSigningFailed` | imgtool failed for another reason | — | Contact LAAVAT Support with the request ID |

See [MCUboot signing](https://docs.laavat.io/usage/signing-encryption/mcuboot-signing/).

## HAB signing with CST (i.MX6, i.MX8M)

`SignHAB` — NXP Code Signing Tool 4.0.1. The platform checks the request and
the binary's layout before CST runs (`cstBlockOutsideImage`, `cstCsfArgumentInvalid`,
`cstIvtNotFound`, `cstCsfPlacementInvalid` and the
[request codes](https://docs.laavat.io/appendixes/error-codes/#codes-for-the-upload-and-requestjson)). `cstImageFileMissing`,
`cstSigningFailed` and a CST rejection of the CSF (`cstCsfArgumentInvalid`)
are failures of CST itself.

| Code | Cause | Example message | Fix |
| --- | --- | --- | --- |
| `cstBlockOutsideImage` | An `authenticate.blocks` entry points outside the binary | `csfs[spl]: authenticate.blocks[0] offset 0x400 and length 0x20000 together exceed file size (0x10000 bytes)` | Take the offsets and lengths from the BSP build or `nxpivt` for this exact binary |
| `cstCsfArgumentInvalid` | An unlock feature SignHAB does not take: one that is not a CST feature, or `JTAG`, `SCS` or `FIELDRETURN`, which need the chip's UID and are not supported. Also CST rejecting a value of the CSF the platform built. An SRK index outside 0 to 3 or a block value that is not a number gives `requestJsonInvalid` | `csfs[spl]: unlock feature MIDD is not known (valid: MFG, MID, OCOTP, RNG)`; `csfs[spl]: unlocking JTAG needs the chip's UID, which SignHAB does not take (valid features: MFG, MID, OCOTP, RNG)` | Use `MFG`, `MID`, `OCOTP` or `RNG`; a JTAG unlock cannot be signed with SignHAB. For a CST rejection, contact LAAVAT Support with the request ID |
| `cstIvtNotFound` | The binary has no IVT where the request expects it, or the IVT fields are invalid, so `authenticate.auto` or raw mode cannot derive the blocks and the signature offset. A raw binary sent without an archive must be the complete i.MX boot image, with its IVT at offset 0 or in the last 32 bytes | `no IVT found: the payload is not an i.MX boot image` | Upload the complete boot image, or give `authenticate.blocks` and `signatureOffset` in archive mode |
| `cstCsfPlacementInvalid` | `signatureOffset` or `csfRegionSize` does not fit the binary: the offset is past its end, the signed CSF does not fit in `csfRegionSize`, or the CSF overlaps an authenticated block | `the signed CSF is 0x2000 bytes and does not fit in csfRegionSize 0x1000` | Take the values from the BSP build or the IVT of this exact binary |
| `cstImageFileMissing` | CST reported that it cannot open or read the image. A `binaryFilename` that is not in the archive gives `requestFileMissing` instead, because the platform checks it before CST runs | — | Contact LAAVAT Support with the request ID |
| `cstSigningFailed` | CST failed for another reason | — | Contact LAAVAT Support with the request ID |

A raw binary sent to a `SignHAB` operation that signs AHAB images fails with
`ahabImageNotContainer` when it holds no AHAB container.

See [CST signing](https://docs.laavat.io/usage/signing-encryption/cstsigning/).

## Windows binary signing

`SignWindowsBinary` — osslsigncode.

| Code | Cause | Example message | Fix |
| --- | --- | --- | --- |
| `winInputNotSignable` | The file is empty, not a PE executable, MSI or CAB, or not in a format Authenticode supports | `Initialization error or unsupported input file type.`; `Unrecognized file type - file is too short: empty.exe` | Upload the build output unmodified |
| `winSigncodeFailed` | osslsigncode failed for another reason, for example the timestamp server could not be reached | — | Retry later for a timestamp failure; otherwise contact LAAVAT Support with the request ID |

See [Windows binary signing](https://docs.laavat.io/usage/signing-encryption/windows-signing/).

## JAR signing

`SignJAVA` — jarsigner (OpenJDK 17).

| Code | Cause | Example message | Fix |
| --- | --- | --- | --- |
| `jarNotZip` | The file is not a zip archive, or its central directory is damaged | `jarsigner: unable to open jar file: text.jar` | Upload the JAR as the build produced it |
| `jarEntryInvalid` | An entry of the JAR cannot be processed | `jarsigner: unable to sign jar: java.util.zip.ZipException: ZipFile invalid LOC header (bad signature)` | Rebuild the JAR |
| `jarVerifyFailed` | The signed JAR did not verify after signing | — | Contact LAAVAT Support with the request ID |
| `jarAlgorithmMismatch` | The signed JAR does not carry the digest or signature algorithm the operation is configured for | — | Contact LAAVAT Support with the request ID |
| `jarSignerFailed` | jarsigner failed for another reason | — | Contact LAAVAT Support with the request ID |

## OP-TEE TA signing

`OP-TEESigning`. The platform reads the TA header before it signs.

| Code | Cause | Example message | Fix |
| --- | --- | --- | --- |
| `opteeNotTaImage` | The file does not start with a TA header: a raw or stripped ELF, an archive, an empty or truncated file | `not a TA image: no TA header (magic 0x4f545348)`; `the TA file is empty` | Upload the `<uuid>.ta` built by the OP-TEE TA dev kit |
| `opteeHeaderUnsupported` | The TA header declares an image type, signature algorithm or digest size the platform does not sign: an encrypted TA, a subkey TA, or another algorithm than RSA with SHA-256 | `unsupported TA image type 2: encrypted TAs are not supported`; `unsupported TA signature algorithm 0x12345678` | Upload a legacy (type 0) or bootstrap (type 1) TA |

The bytes after the TA headers are signed whatever their length, so custom and
partial OP-TEE content can be signed. `img_size` in the signed header is set to
the length that was hashed. The file name is not checked; OP-TEE loads a TA by
the UUID in its file name, so install it on the device as `<uuid>.ta`.

## Codes that are not returned

These codes are in the API description, but no request ends with them. Most
were planned or are replaced by another code; they are listed so a code in the
API description can be looked up.

| Code | What happens instead |
| --- | --- |
| `cstCsfTooLarge` | A signed CSF that does not fit in `csfRegionSize` gives `cstCsfPlacementInvalid` |
| `fitSignatureNotApplied` | When mkimage runs but adds no signature, the request ends with `fitNoSignatureNodes` |
| `mcubootAlreadySigned` | An already signed image gives `mcubootHeaderNotZeroed` or `mcubootImageTooLarge` |
| `ahabFamilyUnsupported` | Reserved: `family` is not checked against the image (see [AHAB signing with SPSDK](https://docs.laavat.io/appendixes/error-codes/#ahab-signing-with-spsdk-imx93)) |
| `opteeSizeMismatch` | Any length after the TA headers is signed, and `img_size` is set to the length that was hashed |
| `opteeDigestMismatch` | The digest is computed over the uploaded file |
| `opteeUuidMismatch` | The file name is not checked |
| `opteeSigningFailed` | A failure that has none of the OP-TEE codes above ends with `defaultErrorStatus` |

## Reading the code with the client

```bash
signing-tool --json imagesigning get -I <request id> | jq '{state, errorStatus, errorDetail}'
```

The output shows `"state": 64`, the `errorStatus` code and, for a signing
tool failure, the `errorDetail` message. The platform's own
messages for a request's validity (HTTP 400 and 422 responses) are returned at
submit time and are not part of this list.
