siyuan-note/siyuan · error

Incorrect master password

Error message

Incorrect master password

What it means

ImportNotebookCryptoBackup returns Conf.Language(311) ('incorrect master password') at line 345 when the KEK derived from the user-supplied password cannot decrypt the backup's KEKVerifier, or the decrypted value does not equal kekVerifierMagic. At this point the file passed all structural/cryptographic integrity checks (valid JSON, complete fields, valid Argon2 params, matching checksum, valid KEKMAC), so the only remaining explanation is a wrong password. This is the offline password-verification gate.

Source

Thrown at kernel/model/crypto.go:345

		return errors.New(Conf.Language(317))
	}

	// 用导入的 salt + 用户输入的主密码派生 KEK，校验能否解开备份里的 verifier
	params, validErr := util.ValidateArgon2Params(nc.KDFParams)
	if validErr != nil {
		return errors.New(Conf.Language(317))
	}
	kek := util.DeriveKey(password, nc.MasterSalt, params)
	defer zeroAndClear(kek)
	if nc.Checksum != computeBackupChecksum(nc) {
		return errors.New(Conf.Language(317))
	}
	if !verifyKEKMAC(nc, kek) {
		return errors.New(Conf.Language(317))
	}
	decrypted, dErr := util.DecryptWithAAD(kek, nc.KEKVerifier, []byte("siyuan:kek-verifier"))
	if dErr != nil || string(decrypted) != string(kekVerifierMagic) {
		return errors.New(Conf.Language(311)) // 主密码错误
	}

	// 校验 KEK 能解密现存笔记本和已删除笔记本历史中的 WrappedDEK，避免导入不匹配的备份。
	if !verifyKEKAgainstExistingBoxes(kek) || !verifyKEKAgainstEncryptedHistory(kek) {
		return errors.New(Conf.Language(316)) // 密钥不匹配
	}

	nc.KDFParams = params // 确保写回 Conf 的参数已经通过完整校验。
	nc.Enabled = true

	// 先写 backup，再提交 conf；backup 失败时 conf 尚未改变，可重试
	if err := writeNotebookCryptoBackupData(nc, kek); err != nil {
		return fmt.Errorf("failed to persist key backup: %w", err)
	}
	Conf.m.Lock()
	*Conf.NotebookCrypto = *nc
	Conf.m.Unlock()
	Conf.Save()

View on GitHub (pinned to 251596fc0d)

Solutions

1. Re-enter the master password used at the time the backup was exported.
2. If the password was since changed, try the previous password that was active when the backup was created.
3. If the password is genuinely lost, the backup cannot be used — encrypted notebook data is unrecoverable by design.

// Retry the import on wrong-password, surface other errors distinctly.
if err := model.ImportNotebookCryptoBackup(data, password); err != nil {
    if strings.Contains(err.Error(), Conf.Language(311)) {
        // wrong password: prompt user to re-enter, do not blame the file
    } else {
        // structural/key-mismatch error: the file or environment is the problem
    }
}

When it happens

Trigger: The user enters a master password that does not match the one used when the backup was created. The derived KEK fails to authenticate-decrypt KEKVerifier, or the plaintext does not match the fixed magic string.

Common situations: User mistypes the master password; backup was created with a different (older) master password before a change-password operation; user confused which password applies to this backup; password manager autofilled the wrong credential.

Related errors

• Cannot import a key backup while encrypted notebooks are ena
• Invalid key backup file
• Decryption failed: incorrect key or corrupted data
• 311
• Encrypted notebooks already exist but the master key backup

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