{"record":{"id":"c2de663228b01594","repo":"benbjohnson/litestream","slug":"invalid-connection-mapping","errorCode":null,"errorMessage":"invalid connection mapping","messagePattern":"invalid connection mapping","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"vfs.go","lineNumber":2931,"sourceCode":"\tfile, err := vfsFileForConnection(dbPtr)\n\tif err != nil {\n\t\treturn 0, err\n\t}\n\tlastPoll := file.LastPollSuccess()\n\tif lastPoll.IsZero() {\n\t\treturn -1, nil\n\t}\n\treturn int64(time.Since(lastPoll).Seconds()), nil\n}\n\nfunc vfsFileForConnection(dbPtr uintptr) (*VFSFile, error) {\n\tv, ok := vfsConnectionMap.Load(dbPtr)\n\tif !ok {\n\t\treturn nil, fmt.Errorf(\"connection not registered\")\n\t}\n\tfileID, ok := v.(uint64)\n\tif !ok {\n\t\treturn nil, fmt.Errorf(\"invalid connection mapping\")\n\t}\n\tfile, ok := lookupVFSFile(fileID)\n\tif !ok {\n\t\treturn nil, fmt.Errorf(\"vfs file not found: id=%d\", fileID)\n\t}\n\treturn file, nil\n}\n\nfunc lookupVFSFile(fileID uint64) (*VFSFile, bool) {\n\tsqlite3vfsFileMux.Lock()\n\tdefer sqlite3vfsFileMux.Unlock()\n\n\tfile, ok := sqlite3vfsFileMap[fileID]\n\tif !ok {\n\t\treturn nil, false\n\t}\n\n\tvfsFile, ok := file.(*VFSFile)","sourceCodeStart":2913,"sourceCodeEnd":2949,"githubUrl":"https://github.com/benbjohnson/litestream/blob/4ed7a308f6271ebfd2b0a6e4b70b03011a37e4a3/vfs.go#L2913-L2949","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Audit any code that writes to vfsConnectionMap — only uint64 file IDs may be stored","Rebuild against a single consistent version of the litestream vfs package","If using a fork, align it with upstream vfs.go registration logic"],"exampleFix":"// before: storing wrong type\nvfsConnectionMap.Store(dbPtr, int(fileID))\n// after: always store uint64\nvfsConnectionMap.Store(dbPtr, uint64(fileID))","handlingStrategy":"validation","validationCode":"if _, ok := v.(uint64); !ok {\n    return fmt.Errorf(\"vfsConnectionMap[%v] holds %T, want uint64\", dbPtr, v)\n}","typeGuard":"func asFileID(v any) (uint64, bool) { id, ok := v.(uint64); return id, ok }","tryCatchPattern":"if _, err := vfsFileForConnection(dbPtr); err != nil && err.Error() == \"invalid connection mapping\" {\n    return fmt.Errorf(\"registry corrupted; rebuild process state\")\n}","preventionTips":["Only store uint64 file IDs in the connection map","Run go test -race on shutdown paths","Avoid mixed/forked litestream vfs versions in one binary"],"tags":["vfs","internal","type-mismatch"],"backgroundTag":"internal-invariant-violation","analyzedSha":"4ed7a308f6271ebfd2b0a6e4b70b03011a37e4a3","analyzedAt":"2026-09-06T18:29:25.564Z","contentChangedAt":"2026-09-06T18:29:25.564Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}