DEV Community

ahmed isam
ahmed isam

Posted on • Originally published at codexpetgenerator.com

Codex Pet Not Showing? 9 Problems and the Exact Fix for Each

#codex #openai #pixelart #troubleshooting

--
title: "Codex Pet Not Showing? 9 Problems and the Exact Fix for Each"
description: "Your custom Codex pet installed but won't appear? Nine real causes — name mismatches in pet.json, missing spritesheets, fake restarts — with the exact fix for each."
tags: ["codex", "openai", "pixelart", "troubleshooting"]

canonical_url: https://codexpetgenerator.com/blog/codex-pet-not-showing-fixes

Codex Pet Not Showing? 9 Problems and the Exact Fix for Each

You dropped your pet into ~/.codex/pets, restarted Codex, and nothing shows up. Before you reinstall anything: codex pet not showing is almost never a broken install.

In my experience helping people with this, three causes cover most cases:

  1. Folder name ≠ pet.json name field. Codex loads a pet from a subfolder and reads the name field inside its pet.json. Folder my-cat-v2 with JSON still saying "my-cat" gets refused. Fix: copy the exact name value, rename the folder, restart.
  2. spritesheet.webp is missing or renamed. Extractors love producing spritesheet (1).webp. The loader looks for the exact filename next to pet.json. Fix: confirm the file sits directly beside pet.json, spelled exactly.
  3. The restart that wasn't a restart. On macOS, closing the window leaves Codex in the menu bar; on Windows it lives in the tray. The pets dir is only re-read at full process exit. Fix: Cmd+Q / tray exit, relaunch.

The other six

  1. pet.json is invalid JSON. A trailing comma or mismatched quote makes Codex skip the pet silently. Validate fast: node -e "JSON.parse(require('fs').readFileSync('pet.json','utf8'))".
  2. Wrong permissions. A folder copied from Downloads with odd perms can be unreadable: chmod -R u+rwX ~/.codex/pets/<name>.
  3. Visibility toggle off. Some Codex versions hide pets behind a settings toggle, especially after updates.
  4. Duplicate pet names. Two subfolders declaring the same name → the loader picks one, the other silently vanishes.
  5. Codex updated and changed the format. A desktop update can change what pet.json expects. Re-download your pet package from the generator.
  6. Spritesheet grid mismatch. pet.json declares 9 states but the sheet has fewer rows → whole pet rejected.

Five-minute checklist

  • ls ~/.codex/pets/<name> — must contain spritesheet.webp and pet.json directly
  • Folder name vs. name field in pet.json — must match
  • Validate pet.json with node
  • Full quit (Cmd+Q / tray), relaunch
  • Check the pets visibility toggle
  • If it worked before an update, re-download the package

Generate a fresh, schema-correct pet here: Codex Pet Generator

中文操作指引（Dev.to 发布）：

跟踪清单：□ 检查 canonical □ 记录数据 □ 回源站博客

Top comments (0)