Reference

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.

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 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.

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.