#Troubleshooting
Error messages are written in English to the result JSON on stdout (the message or problems field), and the notices on stderr are identical. The tables below list all errors and their resolutions by command and stage; for the meaning of the exit codes, see Output, Build Manifest and Exit Codes.
#protect: input
| Error message | Exit code | Cause and resolution |
|---|---|---|
<dir> has no 'game/' directory | 2 | The input directory contains no game/. Pass the root directory of the distribution build, not game/ itself and not the Ren'Py source project directory |
<dir> is already protected (found renmori.rmc) | 2 | renmori.rmc already exists in game/. Run again from a fresh distribution build or the _bak backup |
no 'game/' directory found in the archive | 2 | No build containing game/ was found in the .zip; pass a release archive produced by the launcher |
the archive holds more than one game build (…) | 2 | The top level of the .zip contains several builds. Extract it first, then point renmori at the one to be protected |
unsafe path in archive: <member> | 2 | The archive contains a member that would be extracted outside the target directory, and the command refuses to process it. Regenerate the archive |
output <dir> already exists | 2 | The directory specified by -o, or the output directory derived from the .zip, already exists. Delete the directory or use another path |
nothing to pack under <dir>/game | 2 | There are no files to pack in game/; possibly all of them are matched by exclude, or the build itself is empty |
#protect: configuration and keys
| Error message | Exit code | Cause and resolution |
|---|---|---|
config not found: <path> | 2 | The file specified by -c does not exist |
reading renmori.toml needs Python 3.11+ or the 'tomli' package | 2 | The current Python is older than 3.11 and tomli is not installed. Run pip install tomli or upgrade Python |
<VAR> must be hex | 2 | The environment variable named in [keys] contains non-hexadecimal characters |
<VAR> must be 32 bytes (64 hex chars), got <n> | 2 | The key length is not 32 bytes. Use 64 hexadecimal characters |
<VAR> not set; using a random key (notice) | — | The environment variable named in [keys] does not exist or is empty, so this build uses a random key instead. In CI, check whether the secret has been injected |
#protect: protection strength and plugin
| Error message | Exit code | Cause and resolution |
|---|---|---|
full protection needs the closed plugin; … | 2 | The plugin is required when no strength is set, but it is unavailable: the download was declined, RENMORI_NO_DOWNLOAD is set, the network failed, or no downloadable plugin exists for the current platform. Allow the download, specify a plugin with --plugin or RENMORI_PLUGIN, or explicitly use --strength baseline |
strength '<s>' requires the closed renmori plugin; … | 2 | The specified strength requires the plugin, but the plugin is unavailable or does not support that strength |
Downloaded plugin failed its checksum; discarded (notice) | — | The downloaded file does not match SHA256SUMS and has been discarded. Retry, or check whether the mirror that RENMORI_PLUGIN_BASE_URL points to is complete |
Could not download the plugin: <err> (notice) | — | A network error, or no corresponding entry in SHA256SUMS. Check the network and proxy settings, or use a pre-cached plugin instead |
plugin not found, ignoring: <path> (notice) | — | The file that --plugin or RENMORI_PLUGIN points to does not exist; it has been ignored, and the search continues with the cache or download |
plugin interface <n> unsupported (need <m>); ignoring it (notice) | — | The plugin's interface version is too old. Upgrade the plugin, or delete the cache and download again |
plugin protection failed: <message> | 1 | Plugin execution failed. The original build has been restored, and the incomplete -o output has been deleted. Investigate using the information the plugin printed to stderr |
#protect: execution
| Error message | Exit code | Cause and resolution |
|---|---|---|
backup <dir>_bak already exists; … | 2 | The backup from a previous in-place protection still exists. Delete it, use -o instead, or use --no-backup once you have confirmed that no backup is needed |
{"status": "aborted"} | 2 | y was not answered at the confirmation prompt. No prompt appears in CI |
packing failed: unsupported RPA archive format: … | 1 | The .rpa archive is not in RPA-3.0 or RPA-2.0 format and was usually generated by a third-party tool. Use the standard archives generated by the Ren'Py launcher instead |
packing failed: <err> | 1 | A file read or write error occurred during packing, for example insufficient disk space or a file in use |
warning: could not remove <path>: <err> (notice) | — | Deleting a plaintext original after packing failed. The subsequent renmori verify reports the leftover; delete it manually and verify again |
#verify
| Error message | Exit code | Cause and resolution |
|---|---|---|
no renmori-manifest.json in <dir> | 2 | The directory contains no build manifest. Confirm that the directory passed is the output of protect and that the manifest has not been removed |
missing renmori.rmc | 1 | The container file is missing |
missing renmori.rpe | 1 | The loader extension is missing; the game will be unable to read any protected resource |
container sha mismatch | 1 | The container was modified, replaced or corrupted in transit after protection, or the manifest and container do not belong to the same protection run. Run protect again |
plaintext left: <path> | 1 | A .rpa, .rpyc, .rpy, .rpyb or .rpymc file remains in game/. Common causes: --keep-plaintext was used, deleting the plaintext failed, or files were copied into the directory after protection |
#Issues when running a protected build
| Symptom | Cause and resolution |
|---|---|
| Images or scripts cannot be found after the game starts | The release is missing renmori.rmc or renmori.rpe. Both must be distributed together |
| Protection disappears after building again with the Ren'Py launcher | The launcher rebuilds from the source project. Protection should always be the last step after the build; do not run the launcher on the protected directory |
Scripts matched by exclude cannot be loaded | The runtime loader refuses to open script-type files on disk. Do not exclude scripts |
| The developer console is needed in a test build | Use --no-lockdown to produce an internal test build, and keep lockdown on for release builds |
Ren'Py command-line subcommands such as compile, dialogue and translate are refused | Expected behavior when lockdown is on |
| The Steam SDK does not recognize the game | Confirm that steam_appid.txt is still kept on disk as plaintext. The file is kept by default; if a custom build process is used, check whether it has been removed. For the release workflow, see Releasing to Steam |
| The confirmation prompt never appears in CI | Expected behavior. The prompt appears only in interactive terminals |
| Garbled characters or color control codes appear in the output | Use --no-color, or set the NO_COLOR environment variable |
If an issue is not listed in the tables above, submit a report on GitHub Issues including the command, the output of renmori --version and the complete error message, or email team@mewbaka.cn.