apple/pkl · error · VmException

characterCodingException

characterCodingException

Error message

characterCodingException

What it means

BytesNodes' decode specialization (Bytes.prototype.decode or equivalent) decodes a VmBytes value into a String using the charset named by the String argument. If the bytes are not valid in that charset, the underlying decoder throws CharacterCodingException, which Pkl converts into the `characterCodingException` eval error naming the charset.

Solutions

1. Use a charset that matches the data's actual encoding (e.g. "ISO-8859-1" accepts any byte sequence).
2. Validate the byte content is well-formed for the charset before decoding.
3. If the source may be binary, handle the error and fall back to base64 or hex rendering instead of string decoding.
4. For truncated data, ensure the full byte sequence is read before decoding.

Example fix

// before
text = bytes.decode("US-ASCII")  // throws on bytes > 0x7F
// after
text = bytes.decode("UTF-8")  // or a charset that actually matches the data

try {
  text = bytes.decode(charset)
} catch (error) {
  if (String(error).includes("characterCodingException")) {
    text = bytes.decode("ISO-8859-1") // lossless per-byte fallback
  } else throw error
}

When it happens

Trigger: Calling `bytes.decode(charset)` (BytesNodes.java:123 specialization) where the byte content is not valid for the given charset, e.g. decoding arbitrary bytes as "US-ASCII" or truncated multi-byte UTF-8 sequences as "UTF-8".

Common situations: Decoding binary payloads downloaded from a network as if they were UTF-8 text, reading legacy ISO-8859-1/Windows-1252 data declared as UTF-8, or decoding compressed/encrypted data before decompression.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• abstractMemberCannotHaveBody
• abstractMethodInNonAbstractType
• array
• Cannot convert pkl.base#Int
• Cannot convert pkl.base#Int

AI-assisted analysis of apple/pkl@f3efcbfc9b (2026-09-08). Data as JSON: /api/errors/ef2fd32fb01df3d9. Report an issue: GitHub.

Appendix: source

Thrown at pkl-core/src/main/java/org/pkl/core/stdlib/base/BytesNodes.java:123

      return self.get(index);
    }
  }

  public abstract static class decodeToString extends ExternalMethod1Node {
    @TruffleBoundary
    private String doDecode(VmBytes self, String charset) throws CharacterCodingException {
      var byteBuffer = ByteBuffer.wrap(self.getBytes());
      var decoder = Charset.forName(charset).newDecoder();
      return decoder.decode(byteBuffer).toString();
    }

    @Specialization
    protected String eval(VmBytes self, String charset) {
      try {
        return doDecode(self, charset);
      } catch (CharacterCodingException e) {
        CompilerDirectives.transferToInterpreter();
        throw exceptionBuilder().evalError("characterCodingException", charset).build();
      }
    }
  }
}

View on GitHub (pinned to f3efcbfc9b)