Understanding Geth Sync Modes: Fast, Full, and Light Explained

Method Definition Source Code Analysis

The synchronization modes are defined in eth/downloader/modes.go. The file declares the SyncMode type (an int) and its associated constants, methods, and interface implementations.

package downloader

import "fmt"

// SyncMode represents the synchronisation mode of the downloader.
type SyncMode int

const (
    FullSync SyncMode = iota // Synchronise the entire blockchain history from full blocks
    FastSync                 // Quickly download the headers, full sync only at the chain head
    LightSync                // Download only the headers and terminate afterwards
)

func (mode SyncMode) IsValid() bool {
    return mode >= FullSync && mode <= LightSync
}

func (mode SyncMode) String() string {
    switch mode {
    case FullSync:
        return "full"
    case FastSync:
        return "fast"
    case LightSync:
        return "light"
    default:
        return "unknown"
    }
}

func (mode SyncMode) MarshalText() ([]byte, error) {
    switch mode {
    case FullSync:
        return []byte("full"), nil
    case FastSync:
        return []byte("fast"), nil
    case LightSync:
        return []byte("light"), nil
    default:
        return nil, fmt.Errorf("unknown sync mode %d", mode)
    }
}

func (mode *SyncMode) UnmarshalText(text []byte) error {
    switch string(text) {
    case "full":
        *mode = FullSync
    case "fast":
        *mode = FastSync
    case "light":
        *mode = LightSync
    default:
        return fmt.Errorf(`unknown sync mode %q, want "full", "fast" or "light"`, text)
    }
    return nil
}

SyncMode Type Definition

The SyncMode type is a simple alias for int, allowing the three synchronization strategies to be represented as integer constants.

SyncMode Constants

Three constants are defined using iota: FullSync = 0 FastSync = 1 LightSync = 2

String Interface Implementation

The String() method satisfies Go's fmt.Stringer interface, returning the human‑readable names "full", "fast", "light", or "unknown" for an invalid value.

IsValid Method

IsValid()

simply checks whether the integer value lies between FullSync and LightSync, returning true for valid modes.

TextMarshaler and TextUnmarshaler Implementations

These methods enable SyncMode to be used with Go's encoding packages. MarshalText returns the UTF‑8 byte slice of the mode name, while UnmarshalText parses a byte slice back into the appropriate constant, emitting a descriptive error for unknown strings.

Default Sync Mode Configuration

In cmd/utils/flags.go the default flag is defined:

defaultSyncMode = eth.DefaultConfig.SyncMode
SyncModeFlag = TextMarshalerFlag{
    Name:  "syncmode",
    Usage: `Blockchain sync mode ("fast", "full", or "light")`,
    Value: &defaultSyncMode,
}

The DefaultConfig sets SyncMode to downloader.FastSync, meaning that when no --syncmode argument is supplied, Geth starts in fast sync mode.

Runtime Mode Switching Logic

During protocol manager creation ( eth/handler.go), Geth checks the current blockchain height:

if mode == downloader.FastSync && blockchain.CurrentBlock().NumberU64() > 0 {
    log.Warn("Blockchain not empty, fast sync disabled")
    mode = downloader.FullSync
}

The helper NumberU64() returns the block header number of the latest block:

func (b *Block) NumberU64() uint64 {
    return b.header.Number.Uint64()
}

If the node already contains blocks (height > 0), fast sync is automatically disabled and the mode switches to full sync, ensuring a complete chain download.

Summary of Findings

Geth supports three sync modes: fast, full, and light.

The default mode is fast sync when no --syncmode flag is provided.

On the first launch with an empty chain, fast sync proceeds as configured.

If the node is restarted and the chain already contains blocks, Geth detects the non‑zero height, logs a warning, and forces full sync.

This behavior influences how much data is downloaded and when a full verification of the blockchain occurs.