stablyai/orca · error · Error

Spritesheet file not found.

Error message

Spritesheet file not found.

What it means

Thrown at pet.ts:313-316 when stat(sheetSrc) rejects (any fs error, most commonly ENOENT). This fires after the path is confirmed in-bundle and not a symlink but before checking whether it is a file — so the file simply does not exist at the resolved location.

Source

Thrown at src/main/ipc/pet.ts:316

    const bundleRoot = bundleResolved + sep
    // Why: Windows volumes are case-insensitive; lowercase the prefix compare so case differences can't bypass the escape check.
    const cmp = process.platform === 'win32' ? (s: string) => s.toLowerCase() : (s: string) => s
    if (!cmp(sheetSrc + sep).startsWith(cmp(bundleRoot))) {
      throw new Error('spritesheetPath escapes the bundle.')
    }
    if (await isSymlink(sheetSrc)) {
      throw new Error('spritesheet must not be a symlink.')
    }
    const sheetClass = classifyFile(sheetSrc)
    if (!sheetClass || sheetClass.ext === '.svg') {
      // SVG can't be used as a sprite sheet (no pixel grid).
      throw new Error('Spritesheet must be a PNG, APNG, JPG, GIF, or WebP.')
    }
    let sheetStat: Awaited<ReturnType<typeof stat>>
    try {
      sheetStat = await stat(sheetSrc)
    } catch {
      throw new Error('Spritesheet file not found.')
    }
    if (!sheetStat.isFile()) {
      throw new Error('Spritesheet path is not a file.')
    }
    if (sheetStat.size > MAX_BYTES) {
      throw new Error(
        `Spritesheet is too large (${(sheetStat.size / (1024 * 1024)).toFixed(1)} MB).`
      )
    }

    let sprite: NonNullable<CustomPet['sprite']> | undefined
    if (manifest.frame) {
      // Why: only decode when a frame layout needs validating — nativeImage can fail on some WebP variants in headless contexts.
      const sheetBuf = await readFile(sheetSrc)
      // Why: defend against TOCTOU — file may have grown between stat and read.
      if (sheetBuf.byteLength > MAX_BYTES) {
        throw new Error('Spritesheet exceeded the size limit.')
      }

View on GitHub (pinned to 1136503c6a)

Solutions

1. Verify the exact filename (including case) exists in the bundle directory and matches spritesheetPath.
2. On case-sensitive filesystems (Linux), align the case in spritesheetPath with the actual file.
3. Re-copy the full bundle directory so the image is present.

Example fix

# before — manifest says cat.png but file is Cat.png on Linux
{ "spritesheetPath": "cat.png" }
# after
mv bundle/Cat.png bundle/cat.png  # or update manifest to "Cat.png"

import { stat } from 'node:fs/promises'
async function assertSheetExists(p: string) {
  try { await stat(p) } catch { throw new Error(`spritesheet not found: ${p}`) }
}

try { await importPetBundle(p) }
catch (e) { if (e instanceof Error && e.message === 'Spritesheet file not found.') { /* check filename/case */ } else throw e }

When it happens

Trigger: pet.json's spritesheetPath names a file that is not present in the bundle directory; the file was deleted between the bundle listing and the import; the path has a typo (e.g. 'spritestheepng').

Common situations: Typo in spritesheetPath; bundle was partially copied (missing the image); case-sensitivity mismatch on a case-sensitive filesystem (bundle was 'Cat.png' but manifest says 'cat.png') after copying from macOS/Windows.

Related errors

• Chromium cookies database does not exist
• Spritesheet path is not a file.
• Could not save the pet bundle.
• [plain-node-entry-guard] could not smoke-load daemon-entry.j
• Missing packaged resources directory: ${resourcesDir}

AI-assisted analysis of stablyai/orca@1136503c6a (2026-08-12). Data as JSON: /api/errors/9afae6993608fd49. Report an issue: GitHub.