siyuan-note/siyuan · error

invalid asset download mode

Error message

invalid asset download mode

What it means

SetSyncAssetDownloadMode validation: the requested asset download mode integer is neither 0 (full/download mode) nor 1 (on-demand). Only these two enumerated modes exist for encrypted-notebook asset download; any other value is refused before touching sync state.

Source

Thrown at kernel/model/asset_download.go:300

	return nil
}

// clearAssetDownloadState 在旧密钥仍可认证且全部恢复内容齐全时清除设备状态。
func clearAssetDownloadState() error {
	exists, err := assetDownloadStateExists()
	if err != nil || !exists {
		return err
	}
	repo, err := newRepositoryWithAssetSourceLocked()
	if err != nil {
		return err
	}
	return repo.ClearAssetDownloadState()
}

func SetSyncAssetDownloadMode(mode int) error {
	if mode != 0 && mode != 1 {
		return errors.New("invalid asset download mode")
	}
	lockSync()
	defer unlockSync()
	assetDownloadSourceMu.Lock()
	defer assetDownloadSourceMu.Unlock()
	if mode == 0 {
		if err := ensureAllSyncAssets(); err != nil {
			return err
		}
		exists, err := assetDownloadStateExists()
		if err != nil {
			return err
		}
		if exists {
			repo, repoErr := newRepositoryWithAssetSourceLocked()
			if repoErr != nil {
				return repoErr
			}

View on GitHub (pinned to 8641553a1f)

Solutions

1. Pass exactly 0 (disabled) or 1 (enabled)
2. Clamp/validate the mode value before calling
3. Initialize config fields to 0 rather than leaving them unset

Example fix

// before
mode := cfg.AssetDownloadMode // could be -1
err := model.SetSyncAssetDownloadMode(mode)
// after
if mode != 0 && mode != 1 { mode = 0 }
err := model.SetSyncAssetDownloadMode(mode)

if mode !== 0 && mode !== 1 { throw new Error("mode must be 0 or 1") }
model.SetSyncAssetDownloadMode(mode);

When it happens

Trigger: Calling SetSyncAssetDownloadMode with a value other than 0 or 1, e.g. -1, 2, or an uninitialized int variable.

Common situations: Plugin/kernel API callers guessing mode values; config fields defaulting to a non-0/1 value; tests passing raw integers instead of named constants.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• The cloud sync directory name (Bucket) cannot be empty, cont
• invalid new item template target type [%s]
• invalid appearance mode: %s
• invalid card aspect ratio preset [%v]
• invalid card size preset [%v]

AI-assisted analysis of siyuan-note/siyuan@8641553a1f (2026-09-11). Data as JSON: /api/errors/fbd91571be090628. Report an issue: GitHub.