Troubleshooting

First look at the logs: Settings → Activity shows every install job with its log, and docker logs renplay shows the server. When you report a problem, attach the job log.

An install fails

• Read the job log in Activity. A failed install keeps its download, so you can retry.
• Not enough space. Installs need room in /games for the build, and /games/_renplay/work for scratch space, on the same filesystem.
• Permission denied. The container runs as user 1000. Give that user write access to both folders.
• The engine cannot be downloaded. The first install fetches the Ren’Py web engine from RENPLAY_ENGINES_URL. Check that the server can reach engines.renplay.org. Older Renplay versions use addresses that no longer exist: upgrade.
• “Cannot be installed.” The reason is shown in Add games. Engines that need a desktop (RPG Maker XP, Wolf RPG, Unity PC builds) cannot run in a browser. See Engines.

A game will not start

1. Reload the page and try again. The first start of a big game downloads game.zip and can take a while; the player shows its progress.
2. Open the game’s page in another browser. If it works there, clear site data for Renplay in the first one.
3. Look at the player’s log (the toolbar can download it) for a Python error.
4. Check the catalog: the recipe may say the game needs a different engine version or a patch. Report it if the catalog says nothing.
5. Try pinning another engine with RENPLAY_ENGINE (see Configuration) and reinstalling.

A Ren’Py 7 game stops with a Python error

Games made with Ren’Py 7 or older run on the Ren’Py 8 engine, which uses Python 3. Code written for Python 2 can fail at run time with errors such as xrange, iteritems, unicode or sorting numbers together with text. Renplay patches many of these automatically, but not all. Such games stay broken until the developer updates them or a catalog patch exists. Tell the catalog which game and which error.

A game is slow to start the first time

Games made with an older Ren’Py compile their scripts again on every start in the new engine (it took 17 seconds for one game). Renplay stores the compiled scripts with the build, so only the first start is slow.

Menus are slow or choppy

If a menu is slow while the page is otherwise idle, the browser’s graphics process is the bottleneck, not the images. Renplay already works around the worst case. Try:

• Turn on hardware acceleration in the browser, and update it.
• Close other tabs that use the graphics card.

If it is still slow, report the game, browser and device in Discussions.

Downloads stop with a network error (HTTP/3)

Some gateways drop long downloads on HTTP/3 (ERR_QUIC_PROTOCOL_ERROR in the browser console). The player resumes game.zip by itself with Range requests, and shows an error with a retry button after 8 failures. If it keeps happening, turn HTTP/3 off on your proxy or gateway for Renplay.

iPhone: no fullscreen

Safari on iPhone cannot show any web page full screen. Add Renplay to the Home Screen and open it from there. See Playing.

Network storage is slow

Creating a file on network storage costs a round trip, often 100 to 250 ms on NFS. Renplay keeps streamed assets in one pack per game for that reason, so installs are sequential writes. Still:

• Keep /data on a local disk if you can. The library is a SQLite database, and it dislikes network file systems.
• Keep RENPLAY_DIR on the same filesystem as /games.
• Deleting a game runs in the background so it does not stall the server.

The proxy changes things

Gateways that strip Accept-Encoding or decode gzip break compressed files. Renplay serves the engine as pre-compressed files for that reason. If a game loads halfway and stops, check that the proxy passes Range requests and does not rewrite bodies. See Reverse proxy and HTTPS.

Nothing helps

Ask in Discussions, or open a bug report with the job log.