benbjohnson/litestream · error

invalid connection mapping

Error message

invalid connection mapping

What it means

vfsConnectionMap stores file IDs as uint64. When loading a value for a dbPtr, the code asserts the stored value is a uint64; if not, it reports an invalid connection mapping. This is an internal type-safety check that should be unreachable in normal operation — it signals memory-safety-style corruption of the registry or a caller writing wrong types into the map.

Source

Thrown at vfs.go:2931

	file, err := vfsFileForConnection(dbPtr)
	if err != nil {
		return 0, err
	}
	lastPoll := file.LastPollSuccess()
	if lastPoll.IsZero() {
		return -1, nil
	}
	return int64(time.Since(lastPoll).Seconds()), nil
}

func vfsFileForConnection(dbPtr uintptr) (*VFSFile, error) {
	v, ok := vfsConnectionMap.Load(dbPtr)
	if !ok {
		return nil, fmt.Errorf("connection not registered")
	}
	fileID, ok := v.(uint64)
	if !ok {
		return nil, fmt.Errorf("invalid connection mapping")
	}
	file, ok := lookupVFSFile(fileID)
	if !ok {
		return nil, fmt.Errorf("vfs file not found: id=%d", fileID)
	}
	return file, nil
}

func lookupVFSFile(fileID uint64) (*VFSFile, bool) {
	sqlite3vfsFileMux.Lock()
	defer sqlite3vfsFileMux.Unlock()

	file, ok := sqlite3vfsFileMap[fileID]
	if !ok {
		return nil, false
	}

	vfsFile, ok := file.(*VFSFile)

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Audit any code that writes to vfsConnectionMap — only uint64 file IDs may be stored
2. Rebuild against a single consistent version of the litestream vfs package
3. If using a fork, align it with upstream vfs.go registration logic

Example fix

// before: storing wrong type
vfsConnectionMap.Store(dbPtr, int(fileID))
// after: always store uint64
vfsConnectionMap.Store(dbPtr, uint64(fileID))

if _, ok := v.(uint64); !ok {
    return fmt.Errorf("vfsConnectionMap[%v] holds %T, want uint64", dbPtr, v)
}

func asFileID(v any) (uint64, bool) { id, ok := v.(uint64); return id, ok }

if _, err := vfsFileForConnection(dbPtr); err != nil && err.Error() == "invalid connection mapping" {
    return fmt.Errorf("registry corrupted; rebuild process state")
}

When it happens

Trigger: Another code path storing a non-uint64 value into vfsConnectionMap for a dbPtr; map reuse across process boundaries (e.g. shared memory misuse) or mixed Litestream builds/versions in one binary.

Common situations: Custom forks or patches writing wrong types into the connection map; Cgo/FFI callers corrupting the registry; running mismatched litestream VFS library versions in the same process.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• remote has newer transactions than expected
• failed to marshal request: %w
• read position after sync: %w
• fetch db position: %w
• create per-connection replica client: %w

AI-assisted analysis of benbjohnson/litestream@4ed7a308f6 (2026-09-06). Data as JSON: /api/errors/c2de663228b01594. Report an issue: GitHub.