wavetermdev/waveterm · error

cannot access image file: %v

Error message

cannot access image file: %v

What it means

After resolving the absolute path, setbg calls os.Stat to confirm the file exists and is accessible. If Stat returns an error (file missing, permission denied, broken symlink, etc.) the error is wrapped as "cannot access image file". Nothing was changed; the background is untouched.

Source

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

		// Check for hex color
		if strings.HasPrefix(input, "#") {
			if err := validateHexColor(input); err != nil {
				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)

View on GitHub (pinned to a4447c1563)

Solutions

1. Run `ls -l <path>` yourself to confirm the file exists and is readable
2. Fix typos or use tab-completion to get the exact path
3. Check permissions on the file and its parent directories (chmod/chown as appropriate)
4. If using ~, ensure ExpandHomeDirSafe resolved it; try the absolute path

Example fix

// before
wsh setbg ~/wallpaper.png
// after
# verify first
ls -l ~/wallpaper.png && wsh setbg ~/wallpaper.png

# check accessibility before calling wsh
if [ ! -f "$IMG" ] || [ ! -r "$IMG" ]; then
  echo "cannot read $IMG" >&2; exit 1
fi
wsh setbg "$IMG"

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

try {
  execSync(`wsh setbg "${img}"`, { stdio: "pipe" });
} catch (e) {
  if (String(e.stderr).includes("cannot access image file")) {
    console.error(`File missing or unreadable: ${img}`);
  } else throw e;
}

When it happens

Trigger: `wsh setbg /path/to/missing.png`, a typo'd filename, a file deleted between lookup and call, a symlink pointing nowhere, or a file the current user lacks permission to stat (e.g. parent directory without +x).

Common situations: Typos in the image path; referencing files on an unmounted drive or remote share; sandboxed environments where the wsh process lacks filesystem access; case-sensitive filesystems where the extension case is wrong.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• file does not exist: %q
• accessing file %s: %w
• getting absolute path: %w
• getting file info: %w
• resolving image path: %v

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