multica-ai/multica · warning

--file is required

Error message

--file is required

What it means

Returned by `multica agent avatar <id>` when the --file flag is empty — either not passed at all or passed as an empty string. It is a pure client-side usage check that fires before any filesystem or API access.

Source

Thrown at server/cmd/multica/cmd_agent.go:912

			strVal(t, "id"),
			strVal(t, "issue_id"),
			strVal(t, "status"),
			strVal(t, "created_at"),
		})
	}
	cli.PrintTable(os.Stdout, headers, rows)
	return nil
}

func runAgentAvatar(cmd *cobra.Command, args []string) error {
	client, err := newAPIClient(cmd)
	if err != nil {
		return err
	}

	filePath, _ := cmd.Flags().GetString("file")
	if filePath == "" {
		return fmt.Errorf("--file is required")
	}

	// Validate file exists.
	info, err := os.Stat(filePath)
	if err != nil {
		return fmt.Errorf("file not found: %w", err)
	}

	// Validate extension.
	ext := strings.ToLower(filepath.Ext(filePath))
	validExts := map[string]bool{".png": true, ".jpg": true, ".jpeg": true, ".gif": true, ".webp": true}
	if !validExts[ext] {
		return fmt.Errorf("unsupported file format %q: must be .png, .jpg, .jpeg, .gif, or .webp", ext)
	}

	// Client-side size guard: reject files > 5MB.
	const maxSize = 5 << 20 // 5 MB
	if info.Size() > maxSize {

View on GitHub (pinned to 2c0912b6ec)

Solutions

1. Pass the flag explicitly: `multica agent avatar <id> --file ./avatar.png`
2. In scripts, assert the variable is non-empty before invoking the command
3. Use `multica agent avatar --help` to confirm flag spelling

Example fix

# before
multica agent avatar agt_1
# Error: --file is required

# after
multica agent avatar agt_1 --file ./avatar.png

[ -n "$AVATAR_FILE" ] || { echo '--file is required'; exit 1; }
multica agent avatar "$AGENT_ID" --file "$AVATAR_FILE"

filePath, _ := cmd.Flags().GetString("file")
if filePath == "" {
	return fmt.Errorf("--file is required")
}

When it happens

Trigger: Running `multica agent avatar agt_1` without `--file path.png`, or `--file ""` from a script variable that is unset/empty.

Common situations: Scripted uploads where the file path variable failed to populate (empty env var, wrong argparse key), or forgetting the flag syntax in manual use.

Related errors

• no fields to update; use --name, --description, --instructio
• file not found: %w
• unsupported file format %q: must be .png, .jpg, .jpeg, .gif,
• file too large: %d bytes (max 5MB)
• --skill-ids is required (comma-separated skill IDs; use --sk

AI-assisted analysis of multica-ai/multica@2c0912b6ec (2026-08-15). Data as JSON: /api/errors/5e6a040e6f6c7792. Report an issue: GitHub.