{"record":{"id":"b17e550f43d8ca54","repo":"kovidgoyal/kitty","slug":"failed-to-create-a-shm-file-for-transmission-w","errorCode":null,"errorMessage":"Failed to create a SHM file for transmission: %w","messagePattern":"Failed to create a SHM file for transmission: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"kittens/icat/transmit.go","lineNumber":101,"sourceCode":"}\n\nfunc transmit_shm(imgd *image_data, frame_num int, frame *image_frame) (err error) {\n\tvar mmap shm.MMap\n\tvar data_size int64\n\tif frame.in_memory_bytes == nil {\n\t\tf, err := os.Open(frame.filename)\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"Failed to open image data output file: %s with error: %w\", frame.filename, err)\n\t\t}\n\t\tdefer f.Close()\n\t\tif data_size, err = f.Seek(0, io.SeekEnd); err != nil {\n\t\t\treturn fmt.Errorf(\"Failed to seek in image data output file: %s with error: %w\", frame.filename, err)\n\t\t}\n\t\tif _, err = f.Seek(0, io.SeekStart); err != nil {\n\t\t\treturn fmt.Errorf(\"Failed to seek in image data output file: %s with error: %w\", frame.filename, err)\n\t\t}\n\t\tif mmap, err = shm.CreateTemp(\"icat-*\", uint64(data_size)); err != nil {\n\t\t\treturn fmt.Errorf(\"Failed to create a SHM file for transmission: %w\", err)\n\t\t}\n\t\tif _, err = io.ReadFull(f, mmap.Slice()); err != nil {\n\t\t\tmmap.Close()\n\t\t\tmmap.Unlink()\n\t\t\treturn fmt.Errorf(\"Failed to read data from image output data file: %w\", err)\n\t\t}\n\t} else {\n\t\tdata_size = int64(len(frame.in_memory_bytes))\n\t\tif mmap, err = shm.CreateTemp(\"icat-*\", uint64(data_size)); err != nil {\n\t\t\treturn fmt.Errorf(\"Failed to create a SHM file for transmission: %w\", err)\n\t\t}\n\t\tcopy(mmap.Slice(), frame.in_memory_bytes)\n\t}\n\tdefer mmap.Close() // terminal is responsible for unlink\n\tgc := gc_for_image(imgd, frame_num, frame)\n\tgc.SetTransmission(graphics.GRT_transmission_sharedmem)\n\tgc.SetDataSize(uint64(data_size))\n\terr = gc.WriteWithPayloadTo(os.Stdout, utils.UnsafeStringToBytes(mmap.Name()))","sourceCodeStart":83,"sourceCodeEnd":119,"githubUrl":"https://github.com/kovidgoyal/kitty/blob/6d5d0c440603ad9bdf6dcd599f73f6dde21acb44/kittens/icat/transmit.go#L83-L119","documentation":"The first shm.CreateTemp (for file-backed frame data) failed. icat creates a POSIX shared-memory object (/dev/shm on Linux) sized to the image data; creation can fail if shm is unavailable, full, or size-limited.","triggerScenarios":"Large image where uint64(data_size) exceeds /dev/shm limits; /dev/shm not mounted; RLIMIT/shm permissions deny creation.","commonSituations":"Containers with tiny or missing /dev/shm (Docker default 64MB); huge animated GIF frames; hardened systems restricting shm_open.","solutions":["Increase /dev/shm size (docker --shm-size=..., or tmpfs mount) or scale/resize the image smaller","Force a different transmission path (e.g. --transfer-mode file/stream) so shm isn't used","Check that /dev/shm is mounted and writable"],"exampleFix":"# before\ndocker run ... kitten icat huge.gif\n# after\ndocker run --shm-size=1g ... kitten icat huge.gif","handlingStrategy":"validation","validationCode":"var s syscall.Statfs_t\nsyscall.Statfs(\"/dev/shm\", &s)\navail := s.Bavail * uint64(s.Bsize)\nif avail < uint64(imgSize) { /* resize image or use file/stream transfer */ }","typeGuard":null,"tryCatchPattern":"if err != nil && strings.Contains(err.Error(), \"SHM file\") { /* fallback to --transfer-mode file */ }","preventionTips":["Size /dev/shm to your largest image (docker --shm-size)","Offer --transfer-mode stream as a fallback path"],"tags":["kitty","icat","shm","shared-memory"],"backgroundTag":"shared-memory-allocation-failed","analyzedSha":"6d5d0c440603ad9bdf6dcd599f73f6dde21acb44","analyzedAt":"2026-08-27T14:20:20.142Z","schemaVersion":2},"datasetVersion":"2026-08-27T19:17:21.184Z"}