multica-ai/multica · error

file not found: %w

Error message

file not found: %w

What it means

Wrapped error from os.Stat when the path given to `multica agent avatar --file` cannot be stat'd — the file (or a directory component) does not exist, or permissions deny the lookup. The underlying %w is a *fs.PathError carrying the OS-level cause.

Source

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

	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 {
		return fmt.Errorf("file too large: %d bytes (max 5MB)", info.Size())
	}

	fileData, err := os.ReadFile(filePath)
	if err != nil {
		return fmt.Errorf("read file: %w", err)

View on GitHub (pinned to 2c0912b6ec)

Solutions

1. Check existence: `ls -l <path>`; fix the typo or use an absolute path
2. Quote but expand `~` yourself: use "$HOME/avatar.png" instead of '~/avatar.png'
3. Verify read permission on the file and execute permission on parent directories
4. In scripts, validate the path with `[ -f "$F" ]` before calling the CLI

Example fix

# before
multica agent avatar agt_1 --file '~/pictures/me.png'
# Error: file not found: stat ~/pictures/me.png: no such file or directory

# after
multica agent avatar agt_1 --file "$HOME/pictures/me.png"

[ -f "$AVATAR_FILE" ] || { echo "file not found: $AVATAR_FILE"; exit 1; }
multica agent avatar "$AGENT_ID" --file "$AVATAR_FILE"

func fileExists(p string) bool {
	_, err := os.Stat(p)
	return err == nil && !errors.Is(err, fs.ErrNotExist)
}

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

When it happens

Trigger: `--file ./avatr.png` with a typo, a relative path evaluated from the wrong working directory, a path containing an unexpanded `~`, or a file removed between composing the command and running it.

Common situations: Shell does not expand `~` inside quoted variables; scripts run from a different cwd than assumed; paths copied from another machine; permission-restricted directories.

Related errors

• unsupported file format %q: must be .png, .jpg, .jpeg, .gif,
• --file is required
• file too large: %d bytes (max 5MB)
• read file: %w
• --%s-file %q: empty contents%s

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