Studio GuideWorld SDK Guide
Log In

MATCHMAKE_UNHANDLED error has occurred

If MATCHMAKE_UNHANDLED error occurs during QR test, try the method below to solve it.

Please check the Multiplay server script (index.ts).

  • This error code may occur when the client does not smoothly receive Multiplay Room State data from the server after connecting to multiplay server.
  • Refer to the tutorial below and check the code in the onCreate/onJoin part of the server script (index.ts).


Please refer to the following guide. [ZEPETO Multiplay Tutorial]

Please update the ZEPETO WORLD SDK version to the latest version.

  • Refer to the guide below to check if the ZEPETO WORLD SDK version is up to date, and then update to the latest version.


Please refer to the following guide. [Updating Package]

Please check the Zepeto World Multiplay component.

  • This error might occur if Zepeto World Multiplay components are present in different scenes.
  • Add the Zepeto World Multiplay component to just one scene and follow the example code below to implement it as a singleton.
import { ZepetoScriptBehaviour } from 'ZEPETO.Script';
import { GameObject } from 'UnityEngine';
export default class MultiplayComponent extends ZepetoScriptBehaviour {
    private static _instance: MultiplayComponent = null;
    public static get instance(): MultiplayComponent {
        // If an instance hasn't been created yet, perform the following logic.
        if (this._instance === null) {
            // Search for an instance of type MultiplayComponent within the scene.
            this._instance = GameObject.FindObjectOfType<MultiplayComponent>();
            // If no MultiplayComponent instance is found in the scene, perform the following logic.
            if (this._instance === null) {
                this._instance = new GameObject(<MultiplayComponent>();
        return this._instance;
    private Awake() {
        // If another instance already exists and the current instance is different, execute the following logic.
        if (MultiplayComponent._instance !== null && MultiplayComponent._instance !== this) {
            // Destroy the current GameObject (with the current instance) to prevent duplicate instance creation.
        // If no other instance exists or the current instance is the same, execute the following logic.
        } else {
            MultiplayComponent._instance = this;