siyuan-note/siyuan · warning

ErrSYTargetNotebookRequired

ErrSYTargetNotebookRequired

Error message

target notebook required

What it means

ErrSYTargetNotebookRequired is a sentinel error returned by the auto-detect import path when autoDetect is on, notebook creation was not requested, and no target boxID was supplied — the kernel needs to know which existing notebook to import into. The API handler (kernel/api/import.go:172) checks errors.Is against it to stage the import for user selection instead of failing outright.

Source

Thrown at kernel/model/import.go:167

		}
		return ast.WalkContinue
	})
	return
}

func ImportSY(zipPath, boxID, toPath string) (err error) {
	if isSYNotebookBundle(zipPath) {
		return errors.New(Conf.Language(373))
	}
	_, err = importSY(zipPath, boxID, toPath, false, false)
	return
}

func ImportSYNotebook(zipPath string) (boxID string, err error) {
	return importSY(zipPath, "", "/", true, false)
}

var ErrSYTargetNotebookRequired = errors.New("target notebook required")

func ImportSYAuto(zipPath, boxID, toPath string) (createdBoxID string, notebook bool, err error) {
	createdBoxID, err = importSY(zipPath, boxID, toPath, false, true)
	notebook = err == nil && createdBoxID != boxID
	return
}

func isSYNotebookExport(hasBoxConf, hasBoxDocMeta bool) bool {
	return hasBoxConf || hasBoxDocMeta
}

type importedSYSortDoc struct {
	oldID      string
	newID      string
	sourcePath string
	hidden     bool
}

View on GitHub (pinned to 8641553a1f)

Solutions

1. Pass a valid target notebook (box) ID when calling ImportSYAuto / the import API
2. Handle errors.Is(err, model.ErrSYTargetNotebookRequired) by prompting the user to choose/create a target notebook (as kernel/api/import.go does with stageSYImport)
3. Set createNotebook=true if the intent is to import as a new notebook

Example fix

// before
createdBoxID, notebook, err := model.ImportSYAuto(zipPath, "", toPath)
// after
createdBoxID, notebook, err := model.ImportSYAuto(zipPath, targetBoxID, toPath)
if errors.Is(err, model.ErrSYTargetNotebookRequired) {
    // prompt user for target notebook or stage selection
}

// caller-side check before calling ImportSYAuto
if autoDetect && !createNotebook && boxID == "" {
    return ErrSYTargetNotebookRequired // fail fast locally or prompt for a notebook
}

func isTargetNotebookRequired(err error) bool {
    return errors.Is(err, model.ErrSYTargetNotebookRequired)
}

// Go caller (mirrors kernel/api/import.go:172)
createdBoxID, notebook, err := model.ImportSYAuto(zipPath, boxID, toPath)
if errors.Is(err, model.ErrSYTargetNotebookRequired) {
    // stage the import and ask the user for a target notebook
    return stageSYImport(zipPath)
}

When it happens

Trigger: Calling model.ImportSYAuto(zipPath, "", toPath) (or importSYAuto/importSY0 with autoDetect=true, createNotebook=false, boxID="") for an archive that is not a notebook export, i.e. an ordinary document .sy.zip with no target notebook specified.

Common situations: Automation scripts calling the importSYAuto API endpoint without a notebook parameter; archives containing only documents so auto-detect cannot decide to create a notebook; frontends that omit the notebook field on first import attempt.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Query notebook failed
• notebook not found
• notebook closed
• opened notebook [%s] not found
• Conf.Language(373)

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