juanfont/headscale · error

building sqlite connection URL: %w

Error message

building sqlite connection URL: %w

What it means

headscale serializes its sqlite configuration (pragmas like journal_mode=WAL, wal_autocheckpoint, busy timeout) into a connection URL via sqliteconfig.ToURL(). This error means the assembled configuration could not be rendered into a valid DSN — i.e. some pragma/value combination is unrepresentable.

Source

Thrown at hscontrol/db/db.go:1086

		if err != nil {
			return nil, fmt.Errorf("creating directory for sqlite: %w", err)
		}

		log.Info().
			Str("database", types.DatabaseSqlite).
			Str("path", cfg.Sqlite.Path).
			Msg("Opening database")

		// Build SQLite configuration with pragmas set at connection time
		sqliteConfig := sqliteconfig.Default(cfg.Sqlite.Path)
		if cfg.Sqlite.WriteAheadLog {
			sqliteConfig.JournalMode = sqliteconfig.JournalModeWAL
			sqliteConfig.WALAutocheckpoint = cfg.Sqlite.WALAutoCheckPoint
		}

		connectionURL, err := sqliteConfig.ToURL()
		if err != nil {
			return nil, fmt.Errorf("building sqlite connection URL: %w", err)
		}

		db, err := gorm.Open(
			sqlite.Open(connectionURL),
			&gorm.Config{
				PrepareStmt: cfg.Gorm.PrepareStmt,
				Logger:      dbLogger,
			},
		)

		// The pure Go SQLite library does not handle locking in
		// the same way as the C based one and we can't use the gorm
		// connection pool as of 2022/02/23.
		sqlDB, _ := db.DB()
		sqlDB.SetMaxIdleConns(1)
		sqlDB.SetMaxOpenConns(1)
		sqlDB.SetConnMaxIdleTime(time.Hour)

View on GitHub (pinned to 565fd254d0)

Solutions

1. Sanitize db.path — use a plain absolute path without unusual characters.
2. Reset sqlite tuning options (write_ahead_log, wal_autocheckpoint) to defaults and re-add one at a time.
3. Check the chained error for which pragma failed to encode; fix that config value.

// Defensive wrapper only; fix the sqlite config values (path characters,
// pragma ranges) and re-run. No runtime recovery is meaningful.

When it happens

Trigger: An invalid or contradictory pragma value in cfg.Sqlite (e.g. a WALAutoCheckPoint value that cannot be encoded, or a path containing characters that break URL encoding). Largely a defensive check; normally unreachable with valid config.

Common situations: Manually edited config with out-of-range numeric pragma values; a sqlite path with characters that the URL encoder rejects; version changes to sqliteconfig introducing new required fields left at zero values.

Related errors

• path cannot be empty
• creating directory for sqlite: %w
• database type not supported
• foreign key constraints violated
• busy_timeout must be >= 0

AI-assisted analysis of juanfont/headscale@565fd254d0 (2026-08-15). Data as JSON: /api/errors/2aba65e3d2ea7d74. Report an issue: GitHub.