# PlayDrop MCP upload errors and how to recover

The error shape PlayDrop's MCP tools return, when to retry with the same requestId, and the fix for each common error code.

Source: https://www.playdrop.ai/create/learn/errors

Every PlayDrop MCP tool error keeps its stable `error` code and any details such as `path`, `field`, `name` or `expected`, and adds:

- `message`: what went wrong, in plain words.
- `retryable`: `true` only when the identical call can succeed later.
- `nextAction`: the concrete correction.
- `docsUrl` and `documentationTopic`: the guide to read, also available with `get_documentation`.

## Retry or correct

- **Retryable errors** (temporary failures, rate limits, an interrupted completion): retry the identical call with the same `requestId` after a short wait. Do not create another version.
- **Lost response:** you cannot tell whether it worked, so retry identical content with the same `requestId`. PlayDrop returns the original result instead of publishing twice.
- **Refused input:** fix the named field or file first. Changed content needs a new `requestId`; retrying unchanged input fails again.
- **Partial package results:** completed items stay published. A corrected request should contain only the unfinished work.
- **`send_feedback`** has no retry key. After an ambiguous failure do not resend automatically: the first message may have arrived.

## Common errors

| Code | What to do |
|---|---|
| `advanced_upload_required` | The game uses the SDK, a server, separate files or package-only fields. Keep those features and upload a [package](https://www.playdrop.ai/create/learn/packaging) with a new `requestId`. |
| `invalid_html_file` | The HTML is empty or larger than 10 MiB. Use a package for larger games. |
| `visibility_required` | A package app has no visibility. Set `visibility` on the request or the app: `public`, `unlisted` or `private`. |
| `invalid_visibility` | Use `public`, `unlisted` or `private`. |
| `visibility_conflict` | The request and an app entry ask for different visibilities. Give one, so the audience is never changed silently. |
| `expected_current_version_required` | Add every app's name to `expectedCurrentVersion`: `null` for a new game, otherwise the current version from `list_games`. |
| `current_version_changed` | Someone published a newer version. Call `list_games`, confirm the target with your human, then upload with the current version and a new `requestId`. |
| `game_exists_use_id`, `game_not_found` | Call `list_games`, use the right `gameId` or name, and keep the game's existing name. |
| `request_id_content_conflict` | This `requestId` already belongs to different content. Use a new ID, or resend the original content unchanged. |
| `catalogue_file_missing_or_invalid` | A file was not uploaded or its bytes do not match. Call `prepare_catalogue_upload` again with identical input and the same `requestId`, PUT the missing files, then complete again. |
| `catalogue_files_unclaimed` | Some files are not used by any catalogue entry. Reference them, give listing files `role: "LISTING"` and `app`, or remove them. |
| `entry_point_missing` | `apps[].file` names a file that was not uploaded. Without `file`, the entry defaults to `<name>.html`. |
| `archive_catalogue_required` | Put catalogue.json at the root of the ZIP, not inside a folder. |
| `archive_too_large` | Over 20 MiB compressed: unpack it and upload the folder with signed files, which allows up to 50 MiB per file. Over 200 MiB unpacked: the game itself is too large for one version; compress or remove assets. |
| `procedural_module_validation_unavailable` | Executable procedural 3D or custom-format models cannot be uploaded through MCP. Bake them or reference a published asset. |
| `upload_expired`, `upload_cancelled` | Prepare the upload again with a new `requestId` and complete it within 30 minutes. |
| `invalid_token`, `insufficient_scope` | Reconnect the PlayDrop account in your AI app and allow publishing. |

Catalogue field errors such as an invalid tag, controller declaration or player mode point to the [catalogue.json reference](https://www.playdrop.ai/create/learn/catalogue-json).

## Connection and attachments

- **Expired connection:** an active connection renews itself while it is used. A connection unused for 30 days, or one that expired before this rule, needs to be connected again.
- **Attachment refused:** PlayDrop only downloads files from the host's own attachment service. This is a file-host restriction, not a country restriction. Pass the host-resolved attachment, or upload the files with signed URLs. Never make up a `download_url` or `file_id`.

## Report a problem

If an error looks wrong or the next action does not work, call `send_feedback` once with the tool name, error code, what you sent (without tokens or signed URLs) and what you expected.

## Related guides

- [Publish from your AI app](https://www.playdrop.ai/create/learn/mcp-publishing): How AI agents publish to PlayDrop through MCP: the simple and package paths, private testing, publish_game_version, updates, limits and recovery.
- [Packaging and .play](https://www.playdrop.ai/create/learn/packaging): Lay out a built game folder, ZIP or .play with catalogue.json at its root, declare listing media and servers, and upload it with prepare_catalogue_upload.
- [Troubleshooting](https://www.playdrop.ai/create/learn/troubleshooting): Resolve blocked creation tasks, unclear prompts, missing rewards or earnings, credit limits, and web-game import problems.