What causes "Backup failed: %s" in siyuan-note/siyuan?

Check network connectivity to the cloud provider endpoint and retry the upload

Backup failed: %s

Error message

Backup failed: %s

What it means

A generic catch-all for any UploadTagIndex failure that is NOT the 12-snapshot quota exceeded error. The raw dejavu error is passed through formatRepoErrorMsg to sanitize it, then wrapped in the 'Backup failed: %s' template (Language 84). Common underlying causes include network timeouts, authentication failures, encryption key mismatches, corrupted local index, or insufficient cloud storage.

Source

Thrown at kernel/model/repository.go:1485

			util.PushErrMsg(Conf.Language(29), 5000)
			return
		}
	case conf.ProviderWebDAV, conf.ProviderS3, conf.ProviderLocal:
		if !IsPaidUser() {
			util.PushErrMsg(Conf.Language(214), 5000)
			return
		}
	}

	util.PushEndlessProgress(Conf.Language(116))
	defer util.PushClearProgress()
	uploadFileCount, uploadChunkCount, uploadBytes, err := repo.UploadTagIndex(tag, id, map[string]any{eventbus.CtxPushMsg: eventbus.CtxPushMsgToStatusBarAndProgress})
	if err != nil {
		if errors.Is(err, dejavu.ErrCloudBackupCountExceeded) {
			err = fmt.Errorf(Conf.Language(84), Conf.Language(154))
			return
		}
		err = fmt.Errorf(Conf.Language(84), formatRepoErrorMsg(err))
		return
	}
	msg := fmt.Sprintf(Conf.Language(152), uploadFileCount, uploadChunkCount, humanize.BytesCustomCeil(uint64(uploadBytes), 2))
	util.PushMsg(msg, 5000)
	util.PushStatusBar(msg)
	return
}

func RemoveCloudRepoTag(tag string) (err error) {
	if 1 > len(Conf.Repo.Key) {
		err = errors.New(Conf.Language(26))
		return
	}

	repo, err := newRepository()
	if err != nil {
		return
	}

View on GitHub (pinned to 251596fc0d)

Solutions

Check network connectivity to the cloud provider endpoint and retry the upload
Verify the cloud sync provider credentials in Settings - Account & Sync are still valid (re-login if using SiYuan cloud)
Inspect the kernel log for the detailed formatRepoErrorMsg output to identify the specific underlying cause
If the error persists, check whether Conf.Repo.Key matches the key used to create existing cloud snapshots (a key reset will make old data inaccessible)
Verify cloud storage quota has not been exceeded on the provider side

Example fix

// before
err = model.UploadCloudSnapshot(tag, id)
if err != nil {
    fmt.Println(err)
}

// after
err = model.UploadCloudSnapshot(tag, id)
if err != nil {
    // inspect kernel log for formatRepoErrorMsg detail
    logging.LogErrorf("upload failed: %s", err)
    if errors.Is(err, dejavu.ErrCloudBackupCountExceeded) {
        // handle quota case
    }
}

Defensive patterns

Strategy: retry

Try / catch

// Retry transient upload failures with exponential backoff
maxRetries := 3
for i := 0; i < maxRetries; i++ {
    err = model.UploadCloudSnapshot(tag, id)
    if err == nil {
        break
    }
    if errors.Is(err, dejavu.ErrCloudBackupCountExceeded) {
        break // do not retry quota errors
    }
    time.Sleep(time.Duration(i+1) * 2 * time.Second)
}

Prevention

Implement retry logic for transient network errors (timeouts, connection resets)
Do NOT retry ErrCloudBackupCountExceeded — it is a permanent quota error
Log the detailed error from formatRepoErrorMsg for diagnostics before surfacing to the user

When it happens

Trigger: Calling UploadCloudSnapshot when the underlying repo.UploadTagIndex returns an error other than ErrCloudBackupCountExceeded. This covers network failures to the cloud endpoint, expired or invalid auth tokens, disk I/O errors reading local snapshot data, encryption/decryption failures, or cloud storage quota exhaustion.

Common situations: Intermittent network connectivity to WebDAV/S3/SiYuan cloud servers, expired login sessions (token rotation), mismatched encryption keys after a manual key reset, or local filesystem corruption in the repo directory. Also seen when the cloud storage provider has its own quota separate from the 12-snapshot limit.

Related errors

AI-assisted analysis of siyuan-note/siyuan@251596fc0d (2026-08-12). Data as JSON: /api/errors/38d0103849bd130c. Report an issue: GitHub.