kovidgoyal/kitty · error · OSError

Failed to create a uniquely named SHM file, try shortening t

Error message

Failed to create a uniquely named SHM file, try shortening the prefix from: {prefix}

What it means

After 30 attempts, the constructor could not find a unique unused name for a new shared memory segment using the given prefix. Each attempt uses shm_open with O_CREAT|O_EXCL and a random suffix; 30 consecutive FileExistsError collisions (or a name-format problem with the prefix) aborts with OSError. Long prefixes are the typical culprit since SHM names have a tight length limit (~31 bytes on macOS, 255 on Linux).

Source

Thrown at kitty/shm.py:84

        if not name:
            flags = os.O_CREAT | os.O_EXCL
            if not size:
                raise TypeError("'size' must be > 0")
        else:
            flags = 0
        flags |= os.O_RDONLY if readonly else os.O_RDWR

        tries = 30
        while not name and tries > 0:
            tries -= 1
            q = make_filename(prefix)
            try:
                self._fd = shm_open(q, flags, mode)
                name = q
            except FileExistsError:
                continue
        if tries <= 0:
            raise OSError(f'Failed to create a uniquely named SHM file, try shortening the prefix from: {prefix}')
        if self._fd < 0:
            self._fd = shm_open(name, flags, mode)
        self._name = name
        try:
            if flags & os.O_CREAT and size:
                if hasattr(os, 'posix_fallocate'):
                    os.posix_fallocate(self._fd, 0, size)
                else:
                    os.ftruncate(self._fd, size)
            self.stats = os.fstat(self._fd)
            size = self.stats.st_size
            self._mmap = mmap.mmap(self._fd, size, access=mmap.ACCESS_READ if readonly else mmap.ACCESS_WRITE)
        except OSError:
            self.unlink()
            raise

        self._size = size

View on GitHub (pinned to 6d5d0c4406)

Solutions

Shorten the prefix (a few characters is plenty; randomness provides uniqueness)
Remove any '/' or path-like characters from the prefix
Check /dev/shm (Linux) for leaked segments from previous runs and clean them up

Example fix

// before
shm = SharedMemory(prefix='kitty-glfw-shared-memory-segment-')
// after
shm = SharedMemory(prefix='kglfw-')

Defensive patterns

Strategy: retry

Validate before calling

prefix = prefix[:8].replace('/', '-')
assert '/' not in prefix and len(prefix) <= 16

Try / catch

for p in ('kx-', 'shm-', 's-'):
    try:
        shm = SharedMemory(prefix=p)
        break
    except OSError as e:
        if 'uniquely named' not in str(e):
            raise
else:
    raise

Prevention

Keep prefixes short (<= 8 chars) and free of '/'
Clean up leaked segments in /dev/shm between runs in tests

When it happens

Trigger: Creating a new segment with a very long `prefix` argument; or a prefix containing '/' characters, which makes shm_open interpret the name as a path and fail repeatedly.

Common situations: Using a descriptive prefix like 'my-application-unique-segment-' that exceeds the platform SHM name limit, especially on macOS; embedding path separators in the prefix.

Related errors

AI-assisted analysis of kovidgoyal/kitty@6d5d0c4406 (2026-08-27). Data as JSON: /api/errors/d05727c5eff7a1c4. Report an issue: GitHub.