siyuan-note/siyuan · error

--file is required

Error message

--file is required

What it means

Argument validation in the cobra assetUpload RunE: fires when no --file flag value was supplied. Upload needs at least one file path to copy into the workspace assets directory; invoking `asset upload` with only --id (or with no flags) is the faulting usage.

Solutions

1. Add one or more --file flags: `asset upload --id <id> --file <path> [--file <path2> ...]`.
2. Verify the source list/glob actually produced file paths before invoking the CLI.
3. Check the paths exist and are readable.

Example fix

// before
siyuan asset upload --id 20240101120000-abcdefg
// after
siyuan asset upload --id 20240101120000-abcdefg --file ./img.png

if [ ${#FILES[@]} -eq 0 ]; then echo "no files to upload"; exit 1; fi
ARGS=(); for f in "${FILES[@]}"; do ARGS+=(--file "$f"); done
siyuan asset upload --id "$BLOCK_ID" "${ARGS[@]}"

When it happens

Trigger: Running `asset upload --id <id>` with no --file flags, or `--file ""` only.

Common situations: Building the command programmatically from a file list that ended up empty; forgetting that --file is repeatable and supplying none.

Understand the failure class

Background: "--flag is required" and "must specify" CLI errors: how missing-required-flag validation works and how to fix it — this error's family across 20 libraries.

Related errors

• --av and --ids are required
• --av and --key are required
• --av is required
• --av, --key, --item and --value are required
• --av, --name and --type are required

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

Appendix: source

Thrown at kernel/cli/cmd/asset.go:82

	}
	for _, item := range result.Failed {
		fmt.Fprintf(w, "failed\t%s\t\t%s\n", item.Name, item.Error)
	}
	w.Flush()
}

var assetUploadCmd = &cobra.Command{
	Use:   "upload --id <id> --file <path>",
	Short: "Upload files to workspace assets",
	RunE: func(cmd *cobra.Command, args []string) error {
		id, _ := cmd.Flags().GetString("id")
		if id == "" {
			return fmt.Errorf("--id is required")
		}

		files, _ := cmd.Flags().GetStringArray("file")
		if len(files) == 0 {
			return fmt.Errorf("--file is required")
		}

		for i, f := range files {
			abs, err := filepath.Abs(f)
			if err != nil {
				return err
			}
			files[i] = abs
		}

		if dryRun {
			fmt.Printf("[dry-run] Would upload %d file(s) to document %s\n", len(files), id)
			return nil
		}

		_, succFiles, failedFiles, err := model.InsertLocalAssets(id, files, true)
		if err != nil {
			return err

View on GitHub (pinned to 9f775e8a12)