benbjohnson/litestream · error

connection not registered

Error message

connection not registered

What it means

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).

Source

Thrown at vfs.go:2927

}

// GetVFSConnectionLag returns seconds since last successful poll for a connection.
func GetVFSConnectionLag(dbPtr uintptr) (int64, error) {
	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 {

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Ensure RegisterVFSConnection is called with the sqlite3 db pointer immediately after open and its error checked
2. Check that registration did not fail earlier with 'vfs file not found' — fix that first
3. Avoid UnregisterVFSConnection while the connection is still in use
4. Verify you are passing the same dbPtr the VFS callbacks receive

Example fix

// before: ignoring registration error
_ = litestreamvfs.RegisterVFSConnection(dbPtr, fileID)
// after: fail fast on registration
if err := litestreamvfs.RegisterVFSConnection(dbPtr, fileID); err != nil {
    return fmt.Errorf("register vfs connection: %w", err)
}

if _, ok := vfsConnectionMap.Load(dbPtr); !ok {
    return fmt.Errorf("dbPtr %d not registered; call RegisterVFSConnection after open", dbPtr)
}

file, err := vfsFileForConnection(dbPtr)
if err != nil && err.Error() == "connection not registered" {
    return registerAndRetry(dbPtr, fileID)
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• vfs file not found: id=%d
• remote has newer transactions than expected
• nats: failed to connect: %w
• failed to connect to NATS server: %w
• create per-connection replica client: %w

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