How to debug matchmaking and session issue from the Admin Portal

Last updated on July 18, 2025

Overview

This guide provides a comprehensive approach to troubleshooting matchmaking and session-related issues through the Admin Portal. It outlines the use of diagnostic tools such as Matchmaking X-Ray, Session and Party History, and Player Tracing to monitor ticket flow, analyze session behavior, and track player activity. Following these steps will enable you to resolve issues efficiently or gather the necessary information for further investigation.

Debugging Tools

Matchmaking X-Ray

A. Overview Matchmaking X-Ray

Matchmaking X-Ray is a diagnostic tool used to analyze the matchmaking process in detail. It provides visibility into how tickets are matched, the rules applied, and team composition. This can be especially useful for investigating why certain players are or are not matched together.

You can refer to the Matchmaking X-Ray Guide for more details.

B. Requirements Matchmaking X-Ray

• One of the following identifiers: Session ID, Match Pool, Ticket ID, or User ID
• The date when the issue occurred

C. How to Use Matchmaking X-Ray

1. Navigate to Multiplayer → Diagnostic & Utilities → Matchmaking X-Ray from the sidebar.

2. Navigate to the Timeline tab at the top.

3. Select a filter from the Search by dropdown and input the relevant identifier (e.g., Session ID or Ticket ID).

4. Choose the Date when the issue occurred.

5. Click the Search icon to retrieve the results.

   

   Once results are displayed, you can view the following:

   • Ruleset: The specific ruleset used during the matchmaking process.
   • Match Pool: The pool or group in which the ticket was matched.
   • Worker: The matchmaking worker responsible for processing the ticket.
   • Pod: The service instance handling the matchmaking.
   • Timestamp: The exact time when matchmaking actions occurred.

6. Click the Tickets tab at the bottom of the result to examine individual ticket data.

   

   Once results are displayed, you can view the following:

   • Number of Players per Ticket: How many players are included in each ticket.
   • Ticket Age: Duration since each ticket was created.
   • Average MMR: The average Matchmaking Rating of players in the ticket.
   • Region: The region selected for matchmaking.
   • Latency: Ping/latency values submitted with each ticket.
   • Pivot Ticket: The primary ticket used as the reference point during matchmaking.

7. Click the Team Composition tab at bottom of the result to understand how players are distributed into teams.

   

   Once results are displayed, you can view the following:

   • Average MMR: The average MMR of players within each team.
   • Ticket IDs: The unique identifier of each ticket involved in the match.
   • Pivot Ticket: The ticket used as a base reference when forming teams.
   • Ticket Age: When each ticket was created.
   • Region: The region selected by each party.
   • Latency: Latency information for each player or party.
   • User IDs: User identifiers included in each ticket.
   • Platform: The platform used by each player.
   • Total Tickets and Players Matched: Summary count of matched tickets and players.

Session and Party History

A. Overview Session and Party History

This tool is used to observe and track the history of a session or party session. It is especially useful for investigating debugging session/ party-related issues or verifying session/ party configurations. In the following sections, we will break down Session History and Party History separately to explain their specific purposes, usage, and how to access relevant data for each.

B. Session History

I. Requirements Session History

• One of the following identifiers: Session ID or User ID/ Member ID

II. How to Use Session History

1. Navigate to Multiplayer → Diagnostic & Utilities → Session and Party History from the sidebar.

2. On the Session and Party History page, stay on the Session tab by default.

3. From the Search by dropdown, select either Session ID or User ID / Member ID, depending on the data you have.

4. Enter the value in the input field and click the Search icon to display a list of matching session records.

   

5. Click on a Session ID to view the full session details.

   

   You will see information such as:

   • Session ID: The unique identifier of the session.
   • Session Template: The template configuration used to create the session.
   • Session Created Time: When the session was initialized.
   • Event Timeline: A list of events that occurred within the session.
   • Timestamps: Each event has a recorded time so you can analyze the order and duration between events.

6. You can expand each event using the arrow icon on the left side to see detailed session data in JSON format.

   

C. Party History

I. Requirements Party History

• One of the following identifiers: Party ID or User ID/ Member ID

II. How to Use Party History

1. Navigate to Multiplayer → Diagnostic & Utilities → Session and Party History from the sidebar.

2. Navigate to the Party tab located at the top of the page.

3. From the Search by dropdown, select either Party ID or User ID / Member ID.

4. Enter the appropriate value and click the Search icon to return party session records that match the input.

   

5. Click on a Party ID to view the full party details.

   

   You will see information such as:

   • Party ID: The unique identifier of the party.
   • Session Template: Session Template used when creating the party.
   • Party Created Time: When the party was created.
   • Event Timeline: Similar to session history, this shows all events.
   • Timestamps: Event times are listed in chronological order.

6. As with session history, each event can be expanded by clicking the arrow on the left to view additional details.

   

Player Tracing

A. Overview Player Tracing

Player Tracing is a diagnostic tool used to investigate a player’s activity by tracking their API call history. This is especially useful for debugging account-related issues or tracing specific actions performed by the player within the platform.

B. Requirements Player Tracing

• One of the following identifiers: Email, Display Name, User ID, Creation Date, Third Party Platform, or Public Code.
• The date when the issue occurred

C. How to Use Player Tracing

1. Navigate to Development Utilities → Player Tracing from the sidebar.

2. Select a method from the Search by dropdown (e.g., Email, User ID, etc.), then input the relevant value based on the information you have.

3. Click the Search icon to retrieve player activity results.

   

4. Choose the Date that corresponds with the time the issue occurred.

   

5. Once the results are displayed, locate the relevant row and click the View button to access the API call history.

   

   Once results are displayed, you can view the following:

   • Timestamp of when each API was triggered
   • HTTP Status Code returned from each call (e.g., 200, 400)
   • HTTP Method used (e.g., GET, POST)
   • Service Name that handled the request
   • Endpoint that was called
   • Event associated with the call
   • Event Name triggered by the call

6. You can also click the arrow icon on the left of each API call to expand the entry and view detailed information.

   

   You will see information such as:

   • Call Summary: Shows basic info of the call, like Client ID, Namespace, timestamp, etc.
   • Request Payload: Displays the data sent from the client.
   • Response Data: Displays the data returned by the server.

Use Cases

1. Players Not Joining Session After Successful Matchmaking with 9 Participants

A. Problem

When attempting matchmaking with 9 players using a Matchmaking Ruleset configured to allow between 4 and 16 players, only 7 players successfully entered the gameplay session. The remaining 2 players were not matched and eventually timed out.

B. Investigation

You have the following details:

• 9 User IDs involved in the matchmaking attempt.
• The relevant Session ID.

Now, you can start investigating the matchmaking and the session issue with this information.

1. Session History (via Session ID)

   Gather:

   • List of players who successfully joined the session.
   • Timestamp of when the session was created.
   • If Auto-Accept Session is disabled: Check if all invited players accepted and joined the session manually.

2. Matchmaking X-Ray (via Session ID)

   Review:

   • The pivot player or party ticket.
   • Age of the pivot ticket.
   • All regions involved in the matchmaking process.
   • Latency values per player.
   • Platform used by each player.

3. Player Tracing (via unmatched players' User IDs)

   Check:

   • What occurred on the player side after the match was found and session was created.
   • Player API calls by compare successful vs unmatched players.
   • Any errors or failed calls related to session join or invite handling.

Possible Causes & Solutions

The following are some typical reasons why the issue may occur:

• Player did not join the session after receiving an invitation This applies only when the Auto-Accept Session is disabled in the Session Template.
• Player initiated matchmaking after the session was already created This applies when auto_backfill is set to false in the Matchmaking Ruleset and the Join-ability setting in the Session Template is Closed.
• Player is matchmaking in a different region Regional mismatches can prevent players from being matched into the same session.
• Players are on different platforms while cross-platform play is enabled Platform compatibility may still cause issues even when cross-platform is allowed in the Matchmaking Ruleset.
• Other configuration or connectivity issues Additional factors, such as network errors, incorrect client implementation, or misconfigured matchmaking/session configuration, may also contribute.