henrygd/beszel · warning

system exists

Error message

system exists

What it means

errSystemExists is a sentinel error returned by SystemManager.AddSystem when a system with the same ID is already registered in the manager's store. Beszel throws it to enforce unique system IDs, preventing duplicate SSH connections and duplicate database records for one system.

Source

Thrown at internal/hub/systems/system_manager.go:40

)

// System status constants
const (
	up      string = "up"      // System is online and responding
	down    string = "down"    // System is offline or not responding
	paused  string = "paused"  // System monitoring is paused
	pending string = "pending" // System is waiting on initial connection result

	// interval is the default update interval in milliseconds (60 seconds)
	interval int = 60_000
	// interval int = 10_000 // Debug interval for faster updates

	// sessionTimeout is the maximum time to wait for SSH connections
	sessionTimeout = 4 * time.Second
)

// errSystemExists is returned when attempting to add a system that already exists
var errSystemExists = errors.New("system exists")

// SystemManager manages a collection of monitored systems and their connections.
// It handles system lifecycle, status updates, and maintains both SSH and WebSocket connections.
type SystemManager struct {
	hub           hubLike                               // Hub interface for database and alert operations
	systems       *store.Store[string, *System]         // Thread-safe store of active systems
	sshConfig     *ssh.ClientConfig                     // SSH client configuration for system connections
	smartFetchMap *expirymap.ExpiryMap[smartFetchState] // Stores last SMART fetch time/result; TTL is only for cleanup
	ctx           context.Context                       // Cancelled when the app terminates
	cancel        context.CancelFunc                    // Cancels ctx and all child system contexts
}

// hubLike defines the interface requirements for the hub dependency.
// It extends core.App with system-specific functionality.
type hubLike interface {
	core.App
	GetSSHKey(dataDir string) (ssh.Signer, error)
	HandleSystemAlerts(systemRecord *core.Record, data *system.CombinedData) error

View on GitHub (pinned to b38fb7dafa)

Solutions

1. Check sm.Has(systemId) (or remove the existing system first) before calling AddSystem
2. If intentional replacement, call RemoveSystem(systemID) then AddSystem(sys)
3. Make the incoming System.Id unique in your config or generation logic
4. Treat the sentinel error as idempotent success if the existing system matches the desired one

Example fix

// before
if err := hub.AddSystem(sys); err != nil {
    return err
}
// after
if err := hub.AddSystem(sys); err != nil {
    if errors.Is(err, systems.ErrSystemExists) { // sentinel: already registered
        return nil // idempotent
    }
    return err
}

if manager.Has(sys.Id) {
    return nil // or remove-and-readd if replacement is intended
}
if err := manager.AddSystem(sys); err != nil {
    return err
}

if err := manager.AddSystem(sys); err != nil {
    if errors.Is(err, errSystemExists) { /* already registered; skip or replace */ }
    return err
}

When it happens

Trigger: Calling AddSystem with a System whose Id matches a system already added to the SystemManager (sm.systems.Has(sys.Id) is true).

Common situations: Re-running initialization code on hub restart or hot-reload; adding a host with a duplicated ID in config; a caller like AddRecord retrying after a partial failure; two components both registering the same host.

Related errors

• system not found
• system missing required fields
• ${resp.Error}
• timeout creating session
• no system data in response

AI-assisted analysis of henrygd/beszel@b38fb7dafa (2026-08-31). Data as JSON: /api/errors/7c916c07d4fa5314. Report an issue: GitHub.