What causes "path is a directory, not an image file" in wavetermdev/waveterm?

Pass the path to an actual image file inside the directory, e.g. `wsh setbg ~/Pictures/wall.jpg`

path is a directory, not an image file

Error message

path is a directory, not an image file

What it means

Returned by wsh setbg when the given path exists but is a directory, which cannot be used as a background image.

Source

Thrown at cmd/wsh/cmd/wshcmd-setbg.go:163

				return err
			}
			bgStyle = input
		} else if CssColorNames[strings.ToLower(input)] {
			// Handle CSS color name
			bgStyle = strings.ToLower(input)
		} else {
			// Handle image input
			absPath, err := filepath.Abs(wavebase.ExpandHomeDirSafe(input))
			if err != nil {
				return fmt.Errorf("resolving image path: %v", err)
			}

			fileInfo, err := os.Stat(absPath)
			if err != nil {
				return fmt.Errorf("cannot access image file: %v", err)
			}
			if fileInfo.IsDir() {
				return fmt.Errorf("path is a directory, not an image file")
			}

			mimeType := fileutil.DetectMimeType(absPath, fileInfo, true)
			switch mimeType {
			case "image/jpeg", "image/png", "image/gif", "image/webp", "image/svg+xml":
				// Valid image type
			default:
				return fmt.Errorf("file does not appear to be a valid image (detected type: %s)", mimeType)
			}

			// Create URL-safe path
			escapedPath := filepath.ToSlash(absPath)
			escapedPath = strings.ReplaceAll(escapedPath, "'", "\\'")
			bgStyle = fmt.Sprintf("url('%s')", escapedPath)

			switch {
			case setBgTile:
				bgStyle += " repeat"

View on GitHub (pinned to a4447c1563)

Solutions

Pass the path to an actual image file inside the directory, e.g. `wsh setbg ~/Pictures/wall.jpg`
Check with `test -f <path>` in scripts before invoking setbg
Use `wsh setbg $(ls ~/Pictures/*.png | head -1)` style expansion if you want the first image in a folder

Example fix

// before
wsh setbg ~/Pictures/wallpapers
// after
wsh setbg ~/Pictures/wallpapers/mountain.jpg

Defensive patterns

Strategy: validation

Validate before calling

# require a regular file, not a directory
if [ -d "$IMG" ]; then echo "$IMG is a directory" >&2; exit 1; fi
wsh setbg "$IMG"

Type guard

function isRegularFile(p) {
  try { return require("fs").statSync(p).isFile(); } catch { return false; }
}

Prevention

Use tab-completion to pick files, not directories
In scripts iterating folders, filter to regular files (find -type f)
Check the argument ends with an image extension as a heuristic

When it happens

Trigger: `wsh setbg ~/Pictures` or `wsh setbg .` — passing a directory path instead of an image file.

Common situations: Users pointing at a wallpaper *folder* instead of a file inside it; autocomplete picking a directory; scripts that iterate directories without filtering to files.

Related errors

AI-assisted analysis of wavetermdev/waveterm@a4447c1563 (2026-09-01). Data as JSON: /api/errors/d9c37a03e7f497ac. Report an issue: GitHub.