What causes "close segment: munmap: %w, close contents file: %w" in weaviate/weaviate?

Restart Weaviate to release mappings and file descriptors

close segment: munmap: %w, close contents file: %w

Error message

close segment: munmap: %w, close contents file: %w

What it means

Combined error from segment.close(): unmap of the mmapped contents and/or closing the underlying segment file both failed. Both errors are reported together; either one indicates resource cleanup trouble, often during shutdown or compaction/drop.

Source

Thrown at adapters/repos/db/lsmkv/segment.go:480

}

func (s *segment) close() error {
	var munmapErr, fileCloseErr error
	if s.unMapContents {
		m := mmap.MMap(s.contents)
		munmapErr = m.Unmap()
		stratLabel := s.strategy.String()
		monitoring.GetMetrics().MmapOperations.With(prometheus.Labels{
			"operation": "munmap",
			"strategy":  stratLabel,
		}).Inc()
	}
	if s.contentFile != nil {
		fileCloseErr = s.contentFile.Close()
	}

	if munmapErr != nil || fileCloseErr != nil {
		return fmt.Errorf("close segment: munmap: %w, close contents file: %w", munmapErr, fileCloseErr)
	}

	return nil
}

// sidecarPaths returns the paths of the files derived from the segment: bloom
// filters, count net additions and metadata.
func (s *segment) sidecarPaths() []string {
	paths := make([]string, 0, 3+int(s.secondaryIndexCount))
	paths = append(paths, s.bloomFilterPath())
	for i := 0; i < int(s.secondaryIndexCount); i++ {
		paths = append(paths, s.bloomFilterSecondaryPath(i))
	}
	return append(paths, s.countNetPath(), s.metadataPath())
}

func (s *segment) dropImmediately() error {
	// support for persisting bloom filters and cnas was added in v1.17,

View on GitHub (pinned to 75aa4b6d11)

Solutions

Restart Weaviate to release mappings and file descriptors
Check logs for the specific underlying munmap vs close error
Avoid running the data directory on NFS; use local block storage
If persistent, check kernel memory (vm.max_map_count, memory limits) and host I/O health

Defensive patterns

Strategy: try-catch

Validate before calling

// before close, ensure the segment wasn't already closed/cleaned
if s == nil || s.contentFile == nil && !s.unMapContents {
    return nil // nothing to close
}

Type guard

func isDoubleClose(err error) bool {
    return strings.Contains(err.Error(), "munmap") && strings.Contains(err.Error(), "invalid")
}

Try / catch

if err := seg.close(); err != nil {
    var pe *os.PathError
    if strings.Contains(err.Error(), "close segment: munmap") || errors.As(err, &pe) {
        logger.Warnf("non-fatal segment close issue: %v", err)
    }
}

Prevention

Avoid closing a segment twice (track lifecycle state)
Don't run data on NFS or exotic filesystems
Raise memory limits if munmap failures correlate with memory pressure
Shut down compaction activity before stopping the node

When it happens

Trigger: segment.close() when m.Unmap() fails (e.g. contents already unmapped or invalid mapping) or s.contentFile.Close() fails (e.g. file descriptor issues, I/O error on close).

Common situations: Double-close after a prior shutdown path, memory pressure / mmap errors, NFS or unusual filesystems where unmap/close can fail, shutdown during active I/O.

Related errors

AI-assisted analysis of weaviate/weaviate@75aa4b6d11 (2026-09-04). Data as JSON: /api/errors/9bee38dae5f97f46. Report an issue: GitHub.