syncthing/syncthing · warning · ErrFolderPaused

folder is paused

Error message

folder is paused

What it means

ErrFolderPaused is an exported model error (lib/model/model.go) returned by folder-facing APIs — ScanFolder, Pause/Resume side paths, index handling (indexhandler.go:366) and the folder-state dispatcher — when the target folder exists but is currently paused. Unlike ErrFolderMissing, it indicates a temporary administrative state: the folder configuration is loaded but its service is not running, so scans, pulls, and most REST operations on it are refused.

Source

Thrown at lib/model/model.go:193

	helloMessages                  map[protocol.DeviceID]protocol.Hello
	deviceDownloads                map[protocol.DeviceID]*deviceDownloadState
	remoteFolderStates             map[protocol.DeviceID]map[string]remoteFolderState // deviceID -> folders
	indexHandlers                  *serviceMap[protocol.DeviceID, *indexHandlerRegistry]

	// for testing only
	foldersRunning atomic.Int32
}

var _ config.Verifier = &model{}

type folderFactory func(*model, *ignore.Matcher, config.FolderConfiguration, versioner.Versioner, events.Logger, *semaphore.Semaphore) service

var folderFactories = make(map[config.FolderType]folderFactory)

var (
	errDeviceUnknown    = errors.New("unknown device")
	errDevicePaused     = errors.New("device is paused")
	ErrFolderPaused     = errors.New("folder is paused")
	ErrFolderNotRunning = errors.New("folder is not running")
	ErrFolderMissing    = errors.New("no such folder")
	errNoVersioner      = errors.New("folder has no versioner")
	// errors about why a connection is closed
	errStopped                            = errors.New("Syncthing is being stopped") //nolint:staticcheck
	errEncryptionInvConfigLocal           = errors.New("can't encrypt outgoing data because local data is encrypted (folder-type receive-encrypted)")
	errEncryptionInvConfigRemote          = errors.New("remote has encrypted data and encrypts that data for us - this is impossible")
	errEncryptionNotEncryptedLocal        = errors.New("remote expects to exchange encrypted data, but is configured for plain data")
	errEncryptionPlainForReceiveEncrypted = errors.New("remote expects to exchange plain data, but is configured to be encrypted")
	errEncryptionPlainForRemoteEncrypted  = errors.New("remote expects to exchange plain data, but local data is encrypted (folder-type receive-encrypted)")
	errEncryptionNotEncryptedUntrusted    = errors.New("device is untrusted, but configured to receive plain data")
	errEncryptionPassword                 = errors.New("different encryption passwords used")
	errEncryptionTokenRead                = errors.New("failed to read encryption token")
	errEncryptionTokenWrite               = errors.New("failed to write encryption token")
	errMissingRemoteInClusterConfig       = errors.New("remote device missing in cluster config")
	errMissingLocalInClusterConfig        = errors.New("local device missing in cluster config")
)

View on GitHub (pinned to 058bcd7334)

Solutions

1. Resume the folder first (PATCH /rest/config/folders with paused=false, or GUI), then retry the operation
2. In scripts, check GET /rest/config/folders for the paused flag before calling scan/pull endpoints
3. Treat ErrFolderPaused (via errors.Is) as retryable-with-user-action, distinct from ErrFolderMissing

Example fix

// before
err := model.ScanFolder(folderID)

// after
if err := model.ScanFolder(folderID); errors.Is(err, model.ErrFolderPaused) {
    // resume folder, then retry
}

// Check folder paused flag before folder operations:
for _, fcfg := range cfg.Folders() {
    if fcfg.ID == folderID && fcfg.Paused {
        return errors.New("folder is paused")
    }
}

func isFolderPaused(err error) bool {
    return errors.Is(err, model.ErrFolderPaused)
}

if isFolderPaused(err) {
    // resume folder (config API), then retry the scan/pull operation
}

When it happens

Trigger: Calling model.ScanFolder / ScanFolders / folder runtime methods (model.go:1177, 3239, folder_summary.go) while folder.Paused is true; requesting an index from a paused folder (indexhandler.go returns '%folder: %w' wrapping ErrFolderPaused).

Common situations: REST scripts triggering /rest/db/scan while the folder is paused; startup races where the API answers before the folder is resumed; users pausing folders to save bandwidth and forgetting before scripted syncs; automation pausing all folders on metered connections.

Related errors

• no such folder
• folder has empty ID
• folder has duplicate ID
• folder path not a directory
• folder path missing

AI-assisted analysis of syncthing/syncthing@058bcd7334 (2026-08-15). Data as JSON: /api/errors/17cee63ac80234b1. Report an issue: GitHub.