{"record":{"id":"6f1b9b459e972310","repo":"gravitational/teleport","slug":"failed-to-create-decoder","errorCode":null,"errorMessage":"failed to create decoder","messagePattern":"failed to create decoder","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"lib/srv/desktop/rdp/decoder/decoder.go","lineNumber":108,"sourceCode":"\ntype Decoder struct {\n\tptr *C.RdpDecoder\n}\n\nfunc New(width, height uint16, opts ...Option) (*Decoder, error) {\n\tvar config decoderConfig\n\tfor _, opt := range opts {\n\t\topt(&config)\n\t}\n\n\tptr := C.rdp_decoder_new(\n\t\tC.uint16_t(width),\n\t\tC.uint16_t(height),\n\t\tC.uint16_t(config.ioChannelID),\n\t\tC.uint16_t(config.userChannelID),\n\t)\n\tif ptr == nil {\n\t\treturn nil, errors.New(\"failed to create decoder\")\n\t}\n\n\treturn &Decoder{ptr: ptr}, nil\n}\n\nfunc (d *Decoder) Release() {\n\tif d.ptr == nil {\n\t\treturn\n\t}\n\tC.rdp_decoder_free(d.ptr)\n\td.ptr = nil\n}\n\nfunc (d *Decoder) Resize(width, height uint16) {\n\tif d.ptr == nil {\n\t\treturn\n\t}\n","sourceCodeStart":90,"sourceCodeEnd":126,"githubUrl":"https://github.com/gravitational/teleport/blob/1283425b60ec5f60d509ba4c791183d452923ff7/lib/srv/desktop/rdp/decoder/decoder.go#L90-L126","documentation":"New in lib/srv/desktop/rdp/decoder/decoder.go returns 'failed to create decoder' when the cgo call to construct the native RDP decoder returns a nil pointer. The decoder is created with dimensions, pixel format and channel IDs; a nil native handle means the underlying FreeRDP/decoder initialization failed. Called from handleServerHello, this aborts the RDP/ desktop playback connection.","triggerScenarios":"handleServerHello processes the RDP server hello and calls New with the negotiated width/height, io/user channel IDs; the C decoder allocation fails (invalid dimensions, failed native init, or memory/allocation failure).","commonSituations":"Recording/playback of desktop sessions where the native decoder library is missing or incompatible (version mismatch of bundled FreeRDP), zero/negative negotiated dimensions from a malformed capture, or constrained memory on the host running playback.","solutions":["Update/rebuild Teleport so the bundled native RDP decoder matches the installed platform libraries","Inspect the capture/server hello for zero or absurd width/height values","Reproduce with the desktop RDP playback tooling and check cgo/native library errors in stderr","Ensure the host has enough memory and the correct shared libraries (ldd) available"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// validate dimensions before constructing the decoder\nif width == 0 || height == 0 {\n  return errors.New(\"refusing to create decoder with empty dimensions\")\n}\n// ensure native libs resolve\nif out, err := exec.Command(\"ldd\", decoderLibPath).CombinedOutput(); err != nil {\n  return fmt.Errorf(\"native decoder libs unresolved: %s\", out)\n}","typeGuard":"func decoderReady(d *rdpdecoder.Decoder) bool {\n  return d != nil\n}","tryCatchPattern":"dec, err := rdpdecoder.New(w, h, cfg)\nif err != nil {\n  return fmt.Errorf(\"rdp decoder unavailable: %w\", err)\n}\n// only then use dec for playback","preventionTips":["Never ignore the error from decoder New","Keep native decoder libraries in sync with the Teleport build","Sanitize width/height from server hello before decoder construction"],"tags":["rdp","cgo","decoder","desktop-access","teleport"],"backgroundTag":"decoder-init-failed","analyzedSha":"1283425b60ec5f60d509ba4c791183d452923ff7","analyzedAt":"2026-09-02T04:06:41.601Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}