{"record":{"id":"781242c8d19bbfed","repo":"benbjohnson/litestream","slug":"connection-not-registered","errorCode":null,"errorMessage":"connection not registered","messagePattern":"connection not registered","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"vfs.go","lineNumber":2927,"sourceCode":"}\n\n// GetVFSConnectionLag returns seconds since last successful poll for a connection.\nfunc GetVFSConnectionLag(dbPtr uintptr) (int64, error) {\n\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 {","sourceCodeStart":2909,"sourceCodeEnd":2945,"githubUrl":"https://github.com/benbjohnson/litestream/blob/4ed7a308f6271ebfd2b0a6e4b70b03011a37e4a3/vfs.go#L2909-L2945","documentation":"vfsFileForConnection resolves a SQLite connection handle back to its VFSFile via vfsConnectionMap. If no mapping was ever stored for that dbPtr, this error is returned. It means the connection was never registered (RegisterVFSConnection not called or failed earlier).","triggerScenarios":"VFS xLock/xRead/xWrite callbacks firing for a connection whose RegisterVFSConnection call was skipped, failed (e.g. 645), or whose mapping was removed by UnregisterVFSConnection before the callbacks ran.","commonSituations":"Opening a SQLite connection on the VFS without performing the registration step required by this integration; two-step init where registration errors are silently ignored; connection reuse after the registration map was cleared.","solutions":["Ensure RegisterVFSConnection is called with the sqlite3 db pointer immediately after open and its error checked","Check that registration did not fail earlier with 'vfs file not found' — fix that first","Avoid UnregisterVFSConnection while the connection is still in use","Verify you are passing the same dbPtr the VFS callbacks receive"],"exampleFix":"// before: ignoring registration error\n_ = litestreamvfs.RegisterVFSConnection(dbPtr, fileID)\n// after: fail fast on registration\nif err := litestreamvfs.RegisterVFSConnection(dbPtr, fileID); err != nil {\n    return fmt.Errorf(\"register vfs connection: %w\", err)\n}","handlingStrategy":"try-catch","validationCode":"if _, ok := vfsConnectionMap.Load(dbPtr); !ok {\n    return fmt.Errorf(\"dbPtr %d not registered; call RegisterVFSConnection after open\", dbPtr)\n}","typeGuard":null,"tryCatchPattern":"file, err := vfsFileForConnection(dbPtr)\nif err != nil && err.Error() == \"connection not registered\" {\n    return registerAndRetry(dbPtr, fileID)\n}","preventionTips":["Register every connection right after open and check the error","Never unregister while the connection is live","Use the same dbPtr the VFS callbacks receive"],"tags":["vfs","registration","connection"],"backgroundTag":"resource-not-found","analyzedSha":"4ed7a308f6271ebfd2b0a6e4b70b03011a37e4a3","analyzedAt":"2026-09-06T18:29:25.564Z","contentChangedAt":"2026-09-06T18:29:25.564Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}