juanfont/headscale · error

invalid synchronous

Error message

invalid synchronous

What it means

Error "invalid synchronous" thrown in juanfont/headscale.

Source

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

// 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
//   - Uses additional .wal and .shm files

View on GitHub (pinned to 565fd254d0)

Solutions

1. Inspect the wrapped error for the underlying cause and correct the failing condition (invalid synchronous); 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 (invalid synchronous); retry the operation after fixing the input, configuration, or environment.

When it happens

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

Common situations: Set database.sqlite.synchronous to a valid SQLite synchronous mode (OFF, NORMAL, FULL, EXTRA). NORMAL is recommended with WAL; anything else fails config validation.

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