Troubleshooting

Common issues when generating Pixelsrc sprites with AI and how to fix them.

Format Issues

Invalid JSON

Problem: Output has syntax errors and won't parse.

Symptoms:

Error: expected ',' or '}' at line 1, column 42

Solutions:

Ask the AI to regenerate with explicit validation:

"Output valid JSON, one complete object per line. Verify each line is valid JSON before outputting."
Check for common mistakes:
- Missing commas between key-value pairs
- Trailing commas after last element
- Unquoted string values
- Single quotes instead of double quotes
Use pxl fmt to attempt auto-repair:
```
pxl fmt generated.pxl
```

Wrong Token Format

Problem: Using [skin] or skin instead of {skin}.

Solutions:

Include example in prompt:

"Use curly brace token format: {skin}, {hair}, {_}"
Show the exact format needed:

"Tokens must be wrapped in curly braces. Example: {outline}{skin}{skin}{outline}"

Inconsistent Grid Width

Problem: Rows have different numbers of tokens.

Symptoms:

Warning: Row 3 has 15 tokens but expected 16

Solutions:

Ask for explicit size validation:

"Ensure each row has exactly 16 tokens"
Use strict mode to catch issues:
```
pxl render output.pxl --strict
```
Request the AI double-check:

"After generating, verify that every grid row has exactly the same number of tokens"

Visual Issues

Missing Transparency

Problem: Background is solid instead of transparent.

Solutions:

Explicitly request transparency:

"Use {_} mapped to #00000000 for all background pixels"

Verify the hex code has alpha:

"{_}": "#00000000"  // Correct: 8 digits with 00 alpha
"{_}": "#000000"    // Wrong: 6 digits, fully opaque black

Magenta Pixels in Output

Problem: Rendered image has bright magenta pixels.

Cause: Magenta (#FF00FF) is the error color for undefined tokens.

Solutions:

Check for typos in token names:

// In palette
"{skin}": "#FFCC99"

// In grid - typo!
"{skn}{skn}{skn}"

Ensure all tokens used in grid are defined in palette
Use pxl explain to see which tokens are missing:
```
pxl explain generated.pxl
```

Colors Look Wrong

Problem: Colors don't match expectations.

Solutions:

Verify hex format:
- #RGB - 3 digits, expanded to 6
- #RGBA - 4 digits, expanded to 8
- #RRGGBB - 6 digits, standard
- #RRGGBBAA - 8 digits, with alpha
Check for RGB vs BGR confusion (rare)
Request specific hex values:

"Use #FF0000 for red, not #F00"

Generation Quality Issues

Sprite Looks Stretched/Wrong Proportions

Problem: 16x16 sprite has 15 or 17 rows.

Solutions:

Be explicit about both dimensions:

"Create a 16 pixels wide by 16 pixels tall sprite with exactly 16 rows and 16 tokens per row"
Verify after generation:
```
pxl render generated.pxl --strict
```

Animation Frames Don't Match

Problem: Frames have different sizes or character shifts position.

Solutions:

Define constraints clearly:

"All 4 frames must be exactly 16x16. Keep the character centered. Only animate the legs - head and torso stay in the same position."
Request shared palette first:

"First create a palette called 'walk_colors'. Then create 4 frames all using that palette with identical dimensions."

Details Too Small/Large

Problem: Requested 16x16 but details are too fine or too coarse.

Solutions:

Reference pixel art style:

"NES-style with chunky 2-3 pixel wide lines" "Detailed SNES-style with 1-pixel outlines"
Specify detail level:

"Simple silhouette with minimal detail" "Detailed with visible features like eyes and clothing seams"

Workflow Issues

Inconsistent Palettes Across Sprites

Problem: Related sprites have different colors.

Solutions:

Define palette first:

"Create a palette named 'character_colors' with {skin}: #FFCC99, {hair}: #8B4513, etc. Then create all frames using this palette by name."

Use variants for color swaps instead of regenerating:

{"type": "variant", "name": "hero_red", "base": "hero", "palette": {"{hair}": "#FF0000"}}

Tiles Don't Seamlessly Connect

Problem: Edges don't match when tiles are placed adjacent.

Solutions:

Request seamless design:

"The left edge must match the right edge. The top edge must match the bottom edge. Test by mentally placing 4 copies in a 2x2 grid."
Generate multiple tiles with shared edge constraints:

"Create grass_1 and grass_2 that can be placed adjacent in any order"

Large Image Generation Fails

Problem: AI produces inconsistent or truncated output for large sprites.

Solutions:

Use composition with smaller tiles:

"Create four 16x16 tiles, then compose them into a 32x32 image"

Generate in stages:

Step 1: Create the palette
Step 2: Create top-left 16x16 quadrant
Step 3: Create top-right 16x16 quadrant
...
Final: Compose into 32x32

Verification Commands

# Basic render test
pxl render sprite.pxl -o test.png

# Strict validation (fails on any issue)
pxl render sprite.pxl --strict

# Format check
pxl fmt --check sprite.pxl

# Explain structure
pxl explain sprite.pxl

# Validate without rendering
pxl validate sprite.pxl

Recovery Strategies

When All Else Fails

Start fresh: Ask for a complete regeneration with all constraints restated
Simplify: Request a smaller sprite first, then scale up
Manual fix: Edit the JSONL directly - it's just text
Use lenient mode: Let Pixelsrc auto-fix minor issues (default behavior)

Common Fix Patterns

# Auto-format fixes many issues
pxl fmt broken.pxl -o fixed.pxl

# Lenient render shows warnings but produces output
pxl render broken.pxl -o output.png

# Strict mode for CI/validation only
pxl render sprite.pxl --strict

Pixelsrc Documentation