Troubleshooting
Common errors, what to do about each, and how to recover from interrupted commands.
Commands print JSON (except --help and --version): results on stdout, errors on stderr. Errors include a code, a message that says what to fix and often a next_action. When Rosebud rejects a specific file, filename names it. The CLI overview lists the exit codes.
Unknown results (exit 4)
publish: the game may already exist. Don't publish again right away; a new publish creates a second game.update: run the same command again without changing your files. It won't publish twice, and it sends the media the way the first attempt did. If the folder changed meanwhile, it refuses withpending_operation.pull: run it again. It finishes the work.assets create: run the identical command again. It resumes the same job and won't pay twice.
With outcome not_sent, nothing was released.
When Rosebud throttles a request, the CLI waits as long as Rosebud asks and sends it again, for up to a minute. It never sends a publish or update again on its own.
Common errors
Publishing
| Error | Fix |
|---|---|
state_in_build, or unsafe_path for a hidden file | You published the project root. Publish the build folder, or a copy of the game in ./dist. |
missing_index | Put index.html at the top level of the folder you publish. |
media_path, noncanonical_path | Usually bundler output. Vite adds mixed-case hashes to asset names and copies public/ to the build root. Move public/ media under public/assets/ and set build.rollupOptions.output.assetFileNames to 'assets/[name].[ext]'. |
compressed_limit, expanded_limit, entry_limit, file_limit | The build or a file is too big, or a media file is empty. limit gives the bound. See Limits. |
release_upload_limit | One publish or update adds more than 128 MiB of new media. Send part of it, then update with the rest. |
excluded_file | Remove the credentials, node_modules or .env file the error names. |
duplicate_path | Two names in the folder are the same name in Unicode NFC. Keep one. |
invalid_text | The text file isn't UTF-8, has a NUL byte or holds a private key. Fix it, or move real binary media into assets/. |
unsupported_file, invalid_media | Correct the named file. For editor-only media such as MP4, leave it unchanged at its path, or change it in the Rosebud editor. |
file_changed | A media file changed while uploading, for example during a build. Nothing was sent. Run the command again once the build has finished. |
project_exists | The state file already holds a game. Use rosebud update, or pass a new --state to publish another game. |
login_pending | Your login still waits for approval. Approve it, or run rosebud logout to publish with a claim link. |
game_expired | The claim deadline passed. Publish again as a new game. |
Updating
| Error | Fix |
|---|---|
connection_required, connection_pending | Run rosebud connect and approve its link, then rosebud status. |
invalid_connection, connection_expired, connection_revoked | Access expired or was revoked. Run rosebud connect again. |
version_conflict | The game changed on Rosebud. See Publish updates. |
pull_conflicts | Merge the files the last pull listed, then pull again or pass --expected-version. See rosebud pull. |
directory_mismatch | You last pulled into another folder. Pull into this folder first, or pass --expected-version to release it anyway. |
pending_operation | An earlier update's outcome is unknown. Run it again unchanged, or run rosebud status and pass --expected-version. |
plan_required | pull needs Rosebud Pro or higher on the owner's account. update still works; ask what changed in Rosebud first. |
folder_changed, download_corrupt | A file changed while pull downloaded, or a download arrived damaged. pull left the folder as it was. Run it again. |
sync_unavailable | This Rosebud server can't read files back yet. Nothing changed; try again later. |
unsupported_project | Rosebud can't read this game's files back. Tell the game's owner. |
upload_retry | Rosebud is still checking the game's existing files. Run the same command again. |
project_busy | Rosebud is generating in the game. Wait for it to finish, then run the command again. |
busy | Rosebud is busy and changed nothing. Wait retry_after_seconds, then run the command again. A first publish refused as busy created nothing. |
Assets
| Error | Fix |
|---|---|
login_required | No login on this computer. Run rosebud login. |
invalid_key | The login is pending or was disconnected. Run rosebud whoami, then rosebud login. |
key_expired | The login wasn't used for 90 days. Run rosebud login. |
insufficient_scope | The login lacks the permission in required_scope. Run rosebud logout, then rosebud login. |
insufficient_credits | You need more credits. Buy credits or upgrade on Pricing. Don't retry. |
max_credits | The quote is above --max-credits. Nothing was charged. Raise the cap or choose a cheaper model. |
file_exists | --out already exists. Choose another path, or pass --force to replace it. |
job_unfinished | The wait ran out. Run the identical command again to keep waiting for the same job. |
throttled | Too many requests at once. Wait retry_after_seconds, then run the identical command. |
The HTTP API errors page lists every code Rosebud returns.
Moved the project folder?
The saved game connection is tied to the state file's path. After you move or rename the project folder, commands fail with connection_required. Run rosebud connect again.
Lock files
The CLI locks its state file while a command runs, so run commands against one state file one at a time. If another command holds the lock, the CLI stops with state_locked.
A command stopped with Ctrl+C releases its lock, and a lock left by a process that has stopped is taken over automatically (CLI 0.2.0 and later). On 0.1.0, make sure the crashed command has stopped, then delete the .lock file next to the state file.