{"record":{"id":"ef2fd32fb01df3d9","repo":"apple/pkl","slug":"charactercodingexception","errorCode":"characterCodingException","errorMessage":"characterCodingException","messagePattern":"characterCodingException","errorType":"error_code","errorClass":"VmException","httpStatus":null,"severity":"error","filePath":"pkl-core/src/main/java/org/pkl/core/stdlib/base/BytesNodes.java","lineNumber":123,"sourceCode":"      return self.get(index);\n    }\n  }\n\n  public abstract static class decodeToString extends ExternalMethod1Node {\n    @TruffleBoundary\n    private String doDecode(VmBytes self, String charset) throws CharacterCodingException {\n      var byteBuffer = ByteBuffer.wrap(self.getBytes());\n      var decoder = Charset.forName(charset).newDecoder();\n      return decoder.decode(byteBuffer).toString();\n    }\n\n    @Specialization\n    protected String eval(VmBytes self, String charset) {\n      try {\n        return doDecode(self, charset);\n      } catch (CharacterCodingException e) {\n        CompilerDirectives.transferToInterpreter();\n        throw exceptionBuilder().evalError(\"characterCodingException\", charset).build();\n      }\n    }\n  }\n}\n","sourceCodeStart":105,"sourceCodeEnd":128,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-core/src/main/java/org/pkl/core/stdlib/base/BytesNodes.java#L105-L128","documentation":"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.","triggerScenarios":"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\".","commonSituations":"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.","solutions":["Use a charset that matches the data's actual encoding (e.g. \"ISO-8859-1\" accepts any byte sequence).","Validate the byte content is well-formed for the charset before decoding.","If the source may be binary, handle the error and fall back to base64 or hex rendering instead of string decoding.","For truncated data, ensure the full byte sequence is read before decoding."],"exampleFix":"// before\ntext = bytes.decode(\"US-ASCII\")  // throws on bytes > 0x7F\n// after\ntext = bytes.decode(\"UTF-8\")  // or a charset that actually matches the data","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n  text = bytes.decode(charset)\n} catch (error) {\n  if (String(error).includes(\"characterCodingException\")) {\n    text = bytes.decode(\"ISO-8859-1\") // lossless per-byte fallback\n  } else throw error\n}","preventionTips":["Match the charset to the data's real encoding","Validate byte sequences before decoding","Use ISO-8859-1 as a never-failing fallback","Never decode binary (compressed/encrypted) payloads as text"],"tags":["pkl","bytes","encoding","charset"],"backgroundTag":"invalid-argument-value","analyzedSha":"f3efcbfc9b60d30053b0536d664948d7aa1b8673","analyzedAt":"2026-09-08T13:10:45.570Z","contentChangedAt":"2026-09-08T13:10:45.570Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}