This page covers common issues you may encounter when using Retro Asset Studio and how to resolve them. If your problem is not listed, see Reporting Bugs.

Where are the logs?¶

Retro Asset Studio does not write a log file. When something goes wrong, the app shows the error as a notification in the bottom status bar. Each error notification has a copy-to-clipboard button; use it to grab the exact message, then paste it into a search on this page or into your bug report. A screenshot of the notification works too.

Installation and Startup¶

Windows SmartScreen Warning¶

Symptom: Windows shows "Windows protected your PC" when launching the installer or the portable executable.

Solution: Click More info and then Run anyway. This happens because the alpha builds are not yet code-signed. Step-by-step screenshots are in Installation: Windows SmartScreen warning.

Application Fails to Start (Blank Window)¶

Symptom: The application opens but shows a blank white or black window, or crashes immediately.

Possible causes and solutions:

• Ensure your graphics drivers are up to date.
• Try launching with GPU acceleration disabled: add --disable-gpu to the application shortcut's target.
• Corrupted installation: reinstall the application.
• Corrupted database: rename app.json in the data folder (see Installation: Data Storage) and start the app again. This hides all projects until you restore the file, so keep the renamed copy.

Antivirus Quarantines the Installer¶

Some antivirus products flag unsigned installers. Verify the SHA-256 checksum against the published list, then restore the file and add an exception.

API and Generation Issues¶

"Please configure your … key in Project Settings first"¶

Cause: No API key or token is saved for the provider selected in the current project.

Solution: Go to Project Settings > API Configuration, enter the credential for the selected provider, click Test Connection, then Save Settings. See API Configuration.

Connection Test Fails¶

Hugging Face or OpenAI Cannot Be Selected¶

This is expected. In 0.1.0-alpha.1 those providers are shown in the list but disabled and labelled "Coming soon". Only Google Gemini is enabled. See AI Providers.

Google Gemini Errors¶

Remember that Test Connection for Gemini generates a real image and is billed.

"No images returned"¶

Cause: The provider responded but did not include an image.

Possible solutions:

• Simplify your prompt.
• Ensure the prompt does not violate the provider's content policies.
• Try again (transient API issue).
• Wait a few minutes if the model is overloaded.

Generation Is Very Slow (Over 60 Seconds)¶

Gemini usually answers in 10 to 30 seconds but slows down under load, and the gemini-3-pro-image model is slower than the Flash models. The Spritesheet Generator requests a large wide image and is slower than single sprites.

Solution: Wait for the request to finish. If slowness persists, switch to gemini-2.5-flash-image and check your internet connection speed.

Image Processing¶

Pixel Snap Produces Poor Results¶

Symptom: The pixel-snapped image looks blurry, misaligned, or has too many colors.

Solutions:

• Adjust grid size: The grid overlay in the AI Image tab must align precisely with the pixel boundaries in the generated image. Zoom in to 1:1 and adjust the slider carefully. Watch the output dimensions indicator (e.g., "512x512 -> 64x64") to find common pixel art resolutions.
• Adjust color count: Try different values. Fewer colors (8-16) produce a more stylized look; more colors (32-48) preserve more detail.
• Regenerate: If the AI-generated image does not have a clear pixel grid, generate again. Add "pixel art" or "sharp pixel edges" to your description.

"Pixel snap failed"¶

Cause: The pixel snap process could not process the image.

Solution: Try adjusting the grid size or color count and clicking Get Pixel Perfect again. If the issue persists, regenerate the image.

Colors Look Wrong After Palette Editing¶

Symptom: After editing palette colors, the image has unexpected color patches.

Solution: When you double-click a palette swatch and change its color, all pixels of that color are replaced globally. If the change looks wrong, use Ctrl+Z to undo.

Transparent Color Not Working¶

Symptom: The preview does not show transparency, or the wrong areas are transparent.

Solutions:

• Make sure the transparent color matches the background color in your image exactly. Use the eye dropper or click First to set it to the first palette color.
• Click Generate Preview after setting the transparent color. The preview is not automatic.
• Ensure you are working with a non-background asset. Background assets do not support transparency.

Sprite Is Off-Center or the Wrong Size¶

Use the Image menu: Move Pixels (or Ctrl+Arrow keys) to nudge the sprite, Resize Canvas… to pad it to a clean frame size around an anchor, and Scale Image… to change the resolution with hard pixel edges. See Image menu.

Image Editor¶

Pencil and Eraser Tools Are Not Working¶

In some contexts, the drawing tools are intentionally disabled:

• In the Spritesheet Editor, the T-Pose frame (frame 0) is read-only. Click Edit Original Character to edit it in the Character Designer.
• Tools may be disabled while a processing operation is running (color replacement, preview generation, scaling).

Solution: Wait for any processing to complete, or switch to an editable frame.

Undo/Redo Is Not Working¶

Undo and redo only apply to the Image Editor tab. They track pixel edits, color changes, and Image menu commands.

Solution: Ensure the Image Editor tab is active when pressing Ctrl+Z or Ctrl+Shift+Z.

Image Menu Is Missing from the Title Bar¶

The Image menu only appears while the Image Editor tab is active. Switch to that tab in the Character Designer, Asset Generator, or Spritesheet Editor.

Palette Editor Is Slow¶

Large images (for example 1920x1080 backgrounds) make color replacement, merging, and undo slow because every step keeps a full copy of the image. Work at the target pixel resolution, or scale the image down with Image > Scale Image… before editing.

Pose Editor¶

No Characters in Dropdown¶

Cause: No characters have been created in the current project.

Solution: Go to the Character Designer and create at least one character first.

Skeleton Canvas Is Black or Empty¶

The canvas needs WebGL. Update your graphics driver, and make sure hardware acceleration is not disabled for the app.

Skeleton Joints Do Not Move¶

Symptom: Clicking and dragging on the canvas does not move joints.

Solution: Ensure you are clicking directly on a joint circle (colored dot). The click must land within the hover radius of a joint. Try zooming in or using a larger display.

Generated Pose Does Not Match the Skeleton¶

The AI interprets the skeleton as guidance, not a strict constraint. Results may vary.

Solutions:

• Use the Pose details field to describe the pose in words (e.g., "looking left, arms raised").
• Start from a saved frame that is closer to the desired pose rather than always starting from the T-pose.
• Generate multiple times and keep the best result.
• Use the pixel editor in the Spritesheet Editor to manually adjust individual frames.

Pose Colors Don't Match Character¶

After generation, the system automatically pixel-snaps and palette-maps the output to match your character's colors. If colors still look off:

• Ensure the character has a clean palette (merge similar colors in the character's Image Editor).
• The fewer colors in the palette, the more consistent results tend to be.

Spritesheet Generator¶

Frames Are Misaligned in the Sheet¶

The provider did not follow the two-row grid exactly. Drag and resize the numbered crop boxes to fit each frame, or click Reset to even split and regenerate with fewer frames. See Spritesheet Generator.

The Sheet Does Not Look Like My Character¶

The character's processed sprite is sent to Gemini as a reference image, but the model may still drift on complex motions. Simplify the animation description, reduce the frame count, or try a different Gemini model.

Spritesheet Editor¶

Cannot Edit T-Pose Frame¶

This is by design. The T-Pose in the Spritesheet Editor is read-only. To edit it, click Edit Original Character, which opens the Character Designer in edit mode.

Frames Are Not Loading¶

Cause: Frames are loaded from the database when a character is selected.

Solution: Ensure you have saved frames from the Pose Editor or the Spritesheet Generator for the selected character. The T-Pose always appears as frame 0.

Exported Spritesheet Is Blank or Has Missing Frames¶

Possible causes:

• Frame image files were moved or deleted from disk.
• The character's processed image file is missing.

Solution: Check that all frame files exist in the project's assets\characters\ directory. Delete broken frames in the strip and regenerate them.

Project Management¶

Projects Are Not Loading¶

Possible causes:

• The database file (app.json) is corrupted.
• The application data directory has incorrect permissions.

Solution: Check the data directory (see Installation for the path). If app.json is corrupted, restore it from a backup or rename it to start fresh, then re-import your projects from .rasproj files.

"No project selected"¶

Most tools require an active project. Create a project or select one from the project selector in the title bar.

Import Fails or Reports Warnings¶

• "Cannot import" with a format error means the file is not a valid .rasproj archive or was produced by a newer version of the app.
• Warnings after import mean some files referenced by the project were not in the archive (for example spritesheets exported outside the project folder). The project still works; the affected records point to missing files. The notification names the missing files; use its copy button to keep the list.
• After any import, provider keys are empty by design. Re-enter them in Project Settings.

API Keys Are Gone After Moving to Another PC¶

Keys are encrypted with your Windows user account and are never included in exports. Enter them again in Project Settings on the new machine. See Privacy & Data.

Performance¶

Application Feels Slow with Many Assets¶

Large projects with many high-resolution assets may cause slower loading in the Asset Browser, as all thumbnails are loaded into memory.

Solutions:

• Use type filters to reduce the number of visible assets.
• Keep individual projects focused (e.g., one project per game level).

High Memory Usage¶

Image editing operations hold image data in memory. Each undo step stores a full copy of the image.

Solution: Save your work frequently and restart the application to free memory.

Data Backup¶

Use File > Export Project… or Export All Projects… to create .rasproj backups regularly. See Backup: export & import.