What causes "wal_autocheckpoint must be >= -1" in juanfont/headscale?

wal_autocheckpoint must be >= -1

Error message

wal_autocheckpoint must be >= -1

What it means

Error "wal_autocheckpoint must be >= -1" thrown in juanfont/headscale.

Source

Thrown at hscontrol/db/sqliteconfig/config.go:18

// Package sqliteconfig provides type-safe configuration for SQLite databases
// with proper enum validation and URL generation for modernc.org/sqlite driver.
package sqliteconfig

import (
	"errors"
	"fmt"
	"slices"
	"strings"
)

// Errors returned by config validation.
var (
	ErrPathEmpty           = errors.New("path cannot be empty")
	ErrBusyTimeoutNegative = errors.New("busy_timeout must be >= 0")
	ErrInvalidJournalMode  = errors.New("invalid journal_mode")
	ErrInvalidAutoVacuum   = errors.New("invalid auto_vacuum")
	ErrWALAutocheckpoint   = errors.New("wal_autocheckpoint must be >= -1")
	ErrInvalidSynchronous  = errors.New("invalid synchronous")
	ErrInvalidTxLock       = errors.New("invalid txlock")
)

const (
	// DefaultBusyTimeout is the default busy timeout in milliseconds.
	DefaultBusyTimeout = 10000
)

// JournalMode represents SQLite journal_mode pragma values.
// Journal modes control how SQLite handles write transactions and crash recovery.
//
// Performance vs Durability Tradeoffs:
//
// WAL (Write-Ahead Logging) - Recommended for production:
//   - Best performance for concurrent reads/writes
//   - Readers don't block writers, writers don't block readers
//   - Excellent crash recovery with minimal data loss risk

View on GitHub (pinned to 565fd254d0)

Solutions

Inspect the wrapped error for the underlying cause and correct the failing condition (wal_autocheckpoint must be >= -1); retry the operation after fixing the input, configuration, or environment.

Example fix

Inspect the wrapped error for the underlying cause and correct the failing condition (wal_autocheckpoint must be >= -1); retry the operation after fixing the input, configuration, or environment.

When it happens

Trigger: Thrown at hscontrol/db/sqliteconfig/config.go:18 when the library encounters an invalid state.

Common situations: Set database.sqlite.wal_autocheckpoint to -1 (SQLite default) or a non-negative page count. Values below -1 are rejected during SQLite config validation.

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