siyuan-note/siyuan · error

template already exists, use --overwrite to replace

Error message

template already exists, use --overwrite to replace: %s

What it means

`model.DocSaveAsTemplate` returns code 1 when a template file with the requested name already exists in the templates folder and `--overwrite` was not set. The CLI converts that into this error to protect an existing template from silent replacement.

Solutions

1. Add `--overwrite` to intentionally replace: `siyuan template save-as --id <id> --name mytpl --overwrite`
2. Choose a different `--name`
3. Inspect the templates folder (data/templates/<name>.md) to confirm the existing template can be replaced or back it up first

Example fix

// before
siyuan template save-as --id 20240101120000-abcdefg --name mytpl
// after
siyuan template save-as --id 20240101120000-abcdefg --name mytpl --overwrite

if [ -f "data/templates/$NAME.md" ]; then
  EXTRA="--overwrite"
fi
siyuan template save-as --id "$DOC_ID" --name "$NAME" $EXTRA

if ! siyuan template save-as --id "$ID" --name "$NAME"; then
  echo "template exists; retry with --overwrite or pick a new name" >&2
fi

When it happens

Trigger: Running `siyuan template save-as --id <id> --name <existing-template>` without `--overwrite`; the templates directory already contains `<name>.md`.

Common situations: Re-running an idempotent script a second time; name collision with a template created earlier or synced from another workspace; re-exporting a doc after renaming it to an existing template name.

Understand the failure class

Background: "already exists" / EEXIST / FileAlreadyExistsException: what the 'file already exists' error means and how to fix it — this error's family across 37 libraries.

Related errors

• --id is required
• --name is required
• a document tree plan must be applied in a single transaction
• appearance files not found at
• --attr is required (format: name=value)

AI-assisted analysis of siyuan-note/siyuan@9f775e8a12 (2026-09-19). Data as JSON: /api/errors/1b5d86741ad3c401. Report an issue: GitHub.

Appendix: source

Thrown at kernel/cli/cmd/template.go:164

		id, _ := cmd.Flags().GetString("id")
		name, _ := cmd.Flags().GetString("name")
		if id == "" {
			return fmt.Errorf("--id is required")
		}
		if name == "" {
			return fmt.Errorf("--name is required")
		}
		overwrite, _ := cmd.Flags().GetBool("overwrite")
		if dryRun {
			fmt.Printf("[dry-run] Would save document %s as template \"%s\"\n", id, name)
			return nil
		}
		code, err := model.DocSaveAsTemplate(id, name, overwrite)
		if err != nil {
			return err
		}
		if code == 1 {
			return fmt.Errorf("template already exists, use --overwrite to replace: %s", name)
		}
		fmt.Printf("%s.md\n", name)
		return nil
	},
}

var templateCreateCmd = &cobra.Command{
	Use:   "create --name <name> [--data <markdown> | --file <path>]",
	Short: "Create a template from markdown content",
	RunE: func(cmd *cobra.Command, args []string) error {
		name, _ := cmd.Flags().GetString("name")
		if name == "" {
			return fmt.Errorf("--name is required")
		}
		content, err := resolveData(cmd)
		if err != nil {
			return err
		}

View on GitHub (pinned to 9f775e8a12)