Diagnostics and Logs

When integrating and using TiRTC AI Chat, if you encounter any abnormal behavior, you can use the self-service troubleshooting checklist and log characteristics provided in this document to quickly locate the problem.

Troubleshooting Guide

When a fault occurs, first try to find the corresponding symptom in the table below, and collect logs or perform checks according to the suggestions:

Symptom	Diagnostic Direction / Log Characteristics	Suggestions
Failed to fetch role / returns empty	Server returns HTTP 401 or 403, or the role cannot be found in the console list.	First confirm the existence of the application and role on the Tange open platform. If it's a 401, check the timestamp and AppId in the TGV1 authentication.
Failed to get credentials	Returns HTTP 401 when calling /v1/token/aichat, error code AuthFailure.SignatureFailure, etc.	Check the TGV1 signature calculation. Ensure CanonicalURI is exactly the request path, X-Tg-Date is not too far off, and the Body SHA-256 is correct.
TiRtcWhipConnect fails	Callback err != 0, or console reports a timeout.	Request credentials again; they may have expired. Verify the device network does not block UDP ports and DNS can correctly resolve Tange cloud domains like api-tirtc.tange365.com.
Connected but no response	Network captures or SDK logs show start_session was not sent, or the server returns an Invalid audio format error.	Check if a valid JSON-RPC start_session request was sent on the TIRTC_AI_SIGNALING (e.g., 0x2100) command channel, and ensure the device_id matches the one used when applying for credentials.
Speaking but no captions	Audio is sent, but no downlink caption events are received.	Check if fi.stream_id, fi.media, and fi.flags (e.g., TIRTC_AUDIOSAMPLE_16K16B1C) perfectly match the declaration in start_session. Mismatched formats cause cloud decoding or VAD recognition failures.
Captions exist but no sound	caption events are updating, but the device is silent.	Check the device downlink decoding logic. Ensure the decoder is initialized according to the output_audio format in the start_session response. Make sure the playback buffer is not being cleared by an accidental interrupt logic at this time.
Interruption ineffective	Playback continues despite the user pressing a button or speaking to interrupt.	Ensure the device has sent the JSON-RPC interrupt method and is using the correct reserved command word (e.g., 0x2100).
Session doesn't close properly	The second call to AI Chat connection reports an error or crossed audio.	Ensure that active termination, platform end_session, network disconnection, and business timeout flows are routed to the same local resource cleanup function, thoroughly executing TiRtcClose and stream cleanup.

Submission Process and Required Information

If the issue cannot be resolved after self-troubleshooting, please make sure to include the following information when contacting technical support or submitting a ticket, so we can quickly locate the problem:

1. Environment and Identification Information
   • Device device_id
   • Application AppId and corresponding role_id
   • The exact time the problem occurred and your time zone
2. Device SDK Logs
   • Provide the TiRTC SDK runtime log file, or the logId obtained after calling the log upload interface.
3. Key Payload Screenshots or Text
   • The sanitized peer_id string for this session (do not provide the complete encrypted token).
   • The sanitized payload text of the start_session message, and the fi.media and fi.flags specified when sending.
4. Reproduction Path
   • A description of the shortest consistent reproduction path: "Get role_id -> Request credentials -> Establish connection -> Send start_session -> Send audio -> Receive events".