siyuan-note/siyuan · error

map file [%s] failed: %s

Error message

map file [%s] failed: %s

What it means

WriteFileByMmap guard: mmap.Map of the truncated file failed (memory exhaustion, address-space limits, or filesystem lacking mmap support). The mmap fast-path write of attribute-view or tree data cannot proceed; the raw OS error is included.

Source

Thrown at kernel/util/mmap.go:55

func WriteFileByMmap(filePath string, data []byte) (err error) {
	f, err := filelock.OpenFile(filePath, os.O_RDWR|os.O_CREATE, 0644)
	if err != nil {
		return
	}
	defer filelock.CloseFile(f)

	if err = f.Truncate(int64(len(data))); err != nil {
		msg := fmt.Sprintf("truncate file [%s] failed: %s", filePath, err)
		logging.LogError(msg)
		err = errors.New(msg)
		return
	}

	m, err := mmap.Map(f, mmap.RDWR, 0)
	if err != nil {
		msg := fmt.Sprintf("map file [%s] failed: %s", filePath, err)
		logging.LogError(msg)
		err = errors.New(msg)
		return
	}
	defer m.Unmap()

	copy(m, data)
	if err = m.Flush(); err != nil {
		msg := fmt.Sprintf("flush data [%s] failed: %s", filePath, err)
		logging.LogError(msg)
		err = errors.New(msg)
		return
	}
	return
}

View on GitHub (pinned to 8641553a1f)

Solutions

1. Read the wrapped OS error for the concrete mmap failure reason
2. On Linux, raise vm.max_map_count (sysctl -w vm.max_map_count=262144) or restart the kernel to release stale mappings
3. Avoid placing the workspace on network shares that do not support memory-mapped files
4. If the error persists, check free virtual address space / use a 64-bit kernel build

Example fix

// before
sudo sysctl vm.max_map_count // 65530, exhausted
// after
sudo sysctl -w vm.max_map_count=262144
# restart the SiYuan kernel and retry the save

if err := util.WriteFileByMmap(path, data); err != nil {
    if strings.Contains(err.Error(), "map file") {
        // fall back to a plain os.WriteFile path or alert the user
    }
}

When it happens

Trigger: Called via SaveAttributeView or WriteTree when the file descriptor is invalid, the file was truncated to zero then mapping fails, the OS hits a mapping limit (vm.max_map_count exhausted, out of address space on 32-bit), or the file is on a filesystem that does not support mmap.

Common situations: Long-running kernel exhausting mmap regions after many saves (Linux vm.max_map_count); network/SMB/NFS mounts where mmap is unreliable; 32-bit builds on mobile platforms mapping large .av files.

Understand the failure class

Background: "failed to write file", "Could not save figure", "Error saving remote file" — file write failed: causes and fixes across languages and libraries — this error's family across 38 libraries.

Related errors

• truncate file [%s] failed: %s
• flush data [%s] failed: %s
• install local marketplace package failed: %w; rollback faile
• read session file failed: %w
• create session dir failed: %w

AI-assisted analysis of siyuan-note/siyuan@8641553a1f (2026-09-11). Data as JSON: /api/errors/94fbe248f8ca9d31. Report an issue: GitHub.