wavetermdev/waveterm · error

file does not appear to be a valid image (detected type: %s)

Error message

file does not appear to be a valid image (detected type: %s)

What it means

setbg runs fileutil.DetectMimeType on the file and only accepts jpeg, png, gif, webp, and svg+xml. If the detected MIME type is anything else (or text/plain, application/octet-stream, empty), the command refuses with this message including the detected type. This prevents setting non-image data as a background.

Source

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

			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"
			case setBgCenter:
				bgStyle += fmt.Sprintf(" no-repeat center/%s", setBgSize)
			default:
				bgStyle += " center/cover no-repeat"
			}
		}

		meta["bg"] = bgStyle

View on GitHub (pinned to a4447c1563)

Solutions

1. Convert the image to a supported format (png/jpeg/webp/gif/svg), e.g. with ImageMagick: `magick input.bmp output.png`
2. Read the detected type in the error message to see what the file actually is: `file <path>`
3. Re-download or re-export the image if it is corrupt or an HTML error page
4. Avoid BMP/TIFF/HEIC; convert to PNG first

Example fix

// before
wsh setbg wallpaper.bmp
// after
magick wallpaper.bmp wallpaper.png
wsh setbg wallpaper.png

# check the detected type before calling wsh
mime=$(file -b --mime-type "$IMG")
case "$mime" in
  image/jpeg|image/png|image/gif|image/webp|image/svg+xml) ;;
  *) echo "unsupported type: $mime" >&2; exit 1;;
esac
wsh setbg "$IMG"

const SUPPORTED = new Set(["image/jpeg","image/png","image/gif","image/webp","image/svg+xml"]);
function isSupportedImage(mime) {
  return SUPPORTED.has(mime);
}

try {
  execSync(`wsh setbg "${img}"`, { stdio: "pipe" });
} catch (e) {
  const m = String(e.stderr).match(/detected type: (.*)\)/);
  if (m) console.error(`Convert the file; detected ${m[1]}`);
  else throw e;
}

When it happens

Trigger: `wsh setbg file.txt`, `wsh setbg image.bmp` (BMP is unsupported), a renamed file (e.g. a .txt renamed to .png — content sniffing catches it), a corrupt/HTML error page downloaded as .jpg, or a file whose type could not be detected (reported as empty).

Common situations: Unsupported formats like BMP, TIFF, AVIF, HEIC; corrupted downloads; files downloaded from the web that are actually HTML; SVG served with wrong encoding.

Related errors

• badge oref must be a block or tab (got %q)
• unknown --view %q; try one of: term, web, preview, edit, sys
• --workspace and --window are mutually exclusive; specify onl
• cannot parse connection name: %w
• --conn parameter is required

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