What causes "unable to connect successfully: %w" in googleapis/mcp-toolbox?

Check for other processes holding locks: lsof /path/to/db.sqlite3, and close them

unable to connect successfully: %w

Error message

unable to connect successfully: %w

What it means

sqlite Config.Initialize (internal/sources/sqlite/sqlite.go:70) pings the newly opened database with db.PingContext to confirm a real connection works. On failure the db is closed and the error is wrapped as "unable to connect successfully". For SQLite this usually means the file cannot actually be accessed (locked, unreadable, or a connection-time pragma failure).

Source

Thrown at internal/sources/sqlite/sqlite.go:70

	Type         string `yaml:"type" validate:"required"`
	Database     string `yaml:"database" validate:"required"` // Path to SQLite database file
	SQLCommenter *bool  `yaml:"sqlCommenter"`
}

func (r Config) SourceConfigType() string {
	return SourceType
}

func (r Config) Initialize(ctx context.Context, tracer trace.Tracer) (sources.Source, error) {
	db, err := initSQLiteConnection(ctx, tracer, r.Name, r.Database)
	if err != nil {
		return nil, fmt.Errorf("unable to create db connection: %w", err)
	}

	err = db.PingContext(context.Background())
	if err != nil {
		db.Close()
		return nil, fmt.Errorf("unable to connect successfully: %w", err)
	}

	s := &Source{
		Config: r,
		Db:     db,
	}
	return s, nil
}

var _ sources.Source = &Source{}

type Source struct {
	Config
	Db *sql.DB
}

func (s *Source) IsReadOnly() bool {
	return false

View on GitHub (pinned to 8cc6e09de2)

Solutions

Check for other processes holding locks: lsof /path/to/db.sqlite3, and close them
Verify file integrity: run `sqlite3 /path/to/db.sqlite3 'PRAGMA integrity_check;'`
Ensure the filesystem supports SQLite locking properly (avoid NFS for live db files)
Check free disk space — SQLite needs room for its journal/WAL files

Defensive patterns

Strategy: fallback

Validate before calling

// before starting toolbox
out, err := exec.Command("sqlite3", dbPath, "PRAGMA integrity_check;").Output()
if err != nil || !strings.Contains(string(out), "ok") { log.Fatal("sqlite db not healthy or locked") }

Prevention

Run a single toolbox process per sqlite file to avoid lock contention
Enable WAL mode for concurrent readers
Avoid storing live SQLite databases on NFS
Run PRAGMA integrity_check after crashes

When it happens

Trigger: Initialize called where db.PingContext fails after Open: database file locked by another process holding an exclusive lock, file unreadable/corrupt, or a driver-level failure establishing the first connection.

Common situations: Another process holds a write lock (e.g. a separate toolbox instance or sqlite3 CLI in a transaction); db file corrupted; NFS-mounted SQLite file with locking problems; disk full during journal creation.

Related errors

AI-assisted analysis of googleapis/mcp-toolbox@8cc6e09de2 (2026-09-05). Data as JSON: /api/errors/e36f5d2bcd379964. Report an issue: GitHub.