Troubleshooting Guide
This guide tries to help set up a new TSM system. It is based on common problems customers encounter when setting up the system. It is not an exhaustive list and will be extended in the future when new issues are identified.
Authentication Problems
These errors typically occur when the SDK's authentication credentials, such as an incorrect or unauthorized API key, certificate, or OIDC access token, are compromised.
| SDK or TSM | Symptoms | Description |
|---|---|---|
| SDKv1 | tsm authentication failed <mTLS returns some network error I think> oidc access token unauthorized\ |
See a more detailed description of the Authentication Problems here . |
| SDKv2 | unable to fetch protocol information: tsm authentication failed: unauthorized API key |
See a more detailed description of the Authentication Problems here . |
| SDKv2 | unable to fetch protocol information: tsm authentication failed: unauthorized certificate |
See a more detailed description of the Authentication Problems here . |
| SDKv2 | unable to fetch protocol information: tsm authentication failed: unauthorized OIDC access token\ |
See a more detailed description of the Authentication Problems here . |
Metadata Disagreement
Occurs when there is a mismatch or disagreement between the metadata exchanged during the handshake between the player and the server. This can prevent successful communication or connection.
| SDK or TSM | Symptoms | Description |
|---|---|---|
| TSM | error receiving handshake message from player <PlayerID> for session id <SessionID>: metadata disagreement with player <PlayerID> |
See a more detailed description of the Metadata Disagreement here. |
Communication Problems
| SDK or TSM | General Problem | Symptoms | Description |
|---|---|---|---|
| TSM | Invalid public key for player | communication failed: TLS handshake failed: invalid public key for player |
See a more detailed description of the Invalid Public Key for Player here . |
| SDK | Inter node communication problems | tsm operation failed ; node 0 returned 500: Internal Server Error\n sessionID=<SessionID> |
See a more detailed description of Inter Node Communication Problems here . |
| TSM | Inter node communication problems | undefined<br>endpoint error: an error occurred during key generation: timed out while creating channels sessionID=\<SessionID><br>endpoint error: an error occurred during key generation: EOF sessionID=<SessionID>closing unclaimed channel for session id <SessionID> |
See a more detailed description of Inter Node Communication Problems here . |
| SDK | Performance issues running mobile apps in XCode | When running with a mobile app in the XCode development environment. Seeing timeouts in communication, blocked user interface in the app or other slow performance issues. | See a more detailed description of XCode debug performance issues here . |
Protocol Configurations
| SDK or TSM | Error Code | Symptoms | Description |
|---|---|---|---|
| SDK | 404 (Page not found) |
invalid tsm input ; node returned 404: 404 page not found |
See a more detailed description of the Protocol Configurations here. |
General Error Codes
| Error Code | Symptoms |
|---|---|
400 (Bad request) |
The cause of these problems is that the call contains bad parameters. The customer should check the parameters that are used for the method that is failing. |
403 (Forbidden) |
This handles when an operation is not allowed. It depends a bit on the version of the SDK: - SDKv1 & SDKv2: The key does not exist or belong to a different user (e.g. different API Key). - SDKv1: Accessing admin functionality with a user account or user functionality with an admin account. There is a corner case that can give a 403, when the database is not configured correctly. A more detailed description of this scenario can be found here . |
500 (Internal error) |
Any error that cannot be attributed to bad values sent in the command. |
503 (Service unavailable) |
- SDKv1 & SDKv2: Problems communicating with the other MPC nodes. This can be network issues or bad addresses/public keys in the configuration. - SDKv1: If the system is paused for backup and the operation causes changes or deletions in the database. |
Data Collection for the Support Team
If the issue requires escalation to the support team, the following information will significantly aid in diagnosing and resolving the problem. Depending on the issue's complexity, you may not need to collect all details for simpler problems. However, for more intricate cases involving MPC nodes, please include the following:
1. Log Files
- Provide logs with context, not just isolated lines, as surrounding statements may contain crucial insights.
- Include debug-level logs for a more detailed analysis.
- Collect logs from all nodes, including:
- Core MPC nodes.
- Mobile nodes (even though they might be harder to access).
- Refer to the log configuration documentation for guidance on enabling detailed logging.
2. SDK Error Messages
- Share any error messages observed in the SDKs interacting with the MPC nodes.
- Provide the full stack trace or error context if available.
3. Configuration Files
- Include configuration details as recorded in the logs during startup. (Sensitive information will typically be masked in these logs.)
4. Contextual Information
- Frequency and Pattern:
- Indicate whether the issue occurs consistently, at specific times, or randomly.
- Affected Platforms:
- Specify which platforms are experiencing the problem.
- Identify platforms that are functioning as expected.
- Reproduction Steps:
- Provide a minimal, reproducible example of the problem if possible.
- Customer Code:
- If permissible, share the code used to call the SDK to allow for deeper analysis.
📘
Note:
Providing this information upfront will help the support team troubleshoot and resolve issues more quickly.