Troubleshooting

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• services/geminiService.ts
• components/AiDemo.tsx
• components/Chatbot.tsx
• vite.config.ts
• index.tsx
• metadata.json

This document provides guidance for diagnosing and resolving common issues within the AI for Thai EMS application. It covers problems related to configuration, API communication with Google Gemini, and errors within specific UI components like the AI Demo and Chatbot.

Configuration Errors

Configuration issues are a primary source of application failure, most commonly related to the Google Gemini API key.

Missing or Invalid Gemini API Key

The application requires a valid Gemini API key to communicate with the AI services. Without it, all features relying on AI analysis will fail.

Setup Process:

1. The API key must be set as an environment variable named GEMINI_API_KEY. The README.md suggests placing this in a .env.local file.
2. During the build or development server startup, Vite loads this environment variable.
3. The vite.config.ts file defines and exposes this key to the application code via process.env.API_KEY and process.env.GEMINI_API_KEY.

Sources: README.md:12, vite.config.ts:12-13

The following diagram illustrates the API key loading process. A failure at any step will result in API communication errors.

AI Service Communication Failures

Errors can occur when the application attempts to communicate with the Google Gemini API. These are handled within the geminiService.ts file and the components that call it.

Transcript Analysis Errors

The analyzeEmergencyCallWithGemini function in geminiService.ts is responsible for analyzing the emergency call transcript. It includes error handling for API failures.

Error Handling Logic:

1. A try...catch block wraps the entire API call.
2. After receiving a response, it validates that the response text is a valid JSON string by checking if it starts with { and ends with }. If not, it throws an error: "AI response was not in the expected JSON format.".
3. Any other exception caught during the API call (e.g., network error, invalid API key) will cause the function to throw a generic error: "Failed to analyze transcript with AI.".

This error is then caught by the calling component, AiDemo.tsx, which updates the UI to display an error message.

Sources: services/geminiService.ts:35-55, components/AiDemo.tsx:50-55

The sequence diagram below shows the flow of an unsuccessful API call from the AI Demo component.

Chatbot Stream Errors

The Chatbot.tsx component calls sendMessageToChatStream to get a streaming response from the AI. The error handling is managed within the handleSendMessage function in the component itself. If the stream fails to initiate or an error occurs during streaming, the catch block is triggered, setting an error message in the UI.

Sources: components/Chatbot.tsx:94-99

Component-Level Error Handling

Components display specific error messages based on the context of the failure.

AI Demo Simulation (AiDemo.tsx)

The AI Demo component has a dedicated error state. When the runAnalysis function fails, it sets this state with a user-friendly message and stops the simulation.

• Error State: const [error, setError] = useState<string | null>(null);
• Error Trigger: The catch block in runAnalysis.
• UI Message: "An error occurred during analysis. Please ensure your API key is configured correctly."

// components/AiDemo.tsx:52-54
} catch (e) {
  setError('An error occurred during analysis. Please ensure your API key is configured correctly.');
  console.error(e);
  setSimulationState('finished'); // Stop simulation on error
}

Sources: components/AiDemo.tsx:42, 52-56, 140

Chatbot (Chatbot.tsx)

The Chatbot component handles multiple types of errors, including API communication and hardware access.

General Message Errors

If sendMessageToChatStream fails, the handleSendMessage function in Chatbot.tsx catches the error and updates the UI.

• UI Message: "Sorry, I couldn't get a response. Please check your API key and try again."

Sources: components/Chatbot.tsx:95-97

Audio Input Errors

The chatbot's voice input feature requires microphone access and a live connection to the Gemini API for transcription.

1. Microphone Access: If the user denies microphone permission, navigator.mediaDevices.getUserMedia({ audio: true }) will throw an error.
   • UI Message: "Microphone access is required for audio input."
   • This permission requirement is declared in metadata.json.
2. Live Transcription: An error during the live transcription session (e.g., connection lost) is handled by the onerror callback.
   • UI Message: "Error during transcription."

Sources: components/Chatbot.tsx:110-116, 150-154, metadata.json:4-6

The following flowchart shows the logic for starting an audio recording and handling potential errors.

Common Error Messages Summary

The table below summarizes error messages displayed in the UI, their origins in the code, and potential solutions.

Error Message	Source File	Cause	Suggested Solution
An error occurred during analysis. Please ensure your API key is configured correctly.	components/AiDemo.tsx:53	The call to analyzeEmergencyCallWithGemini failed.	Verify the GEMINI_API_KEY in .env.local is correct. Check network connection.
Sorry, I couldn't get a response. Please check your API key and try again.	components/Chatbot.tsx:96	The call to sendMessageToChatStream failed.	Verify the GEMINI_API_KEY. Check network connection.
Microphone access is required for audio input.	components/Chatbot.tsx:158	The browser blocked access to the microphone.	Allow microphone access in browser settings for this site.
Error during transcription.	components/Chatbot.tsx:139	The live transcription session with Gemini encountered an error.	Check network connection and try again.
AI response was not in the expected JSON format.	services/geminiService.ts:49	The Gemini API returned data that was not a parsable JSON object.	This may be a transient API issue or a problem with the prompt/schema.

Application Initialization

A fundamental error can occur if the main HTML file is modified incorrectly. The application's entry point, index.tsx, expects to find a DOM element with the ID root.

// index.tsx:5-7
const rootElement = document.getElementById('root');
if (!rootElement) {
  throw new Error("Could not find root element to mount to");
}

If this element is missing from index.html, the application will fail to start and throw an error. Ensure the index.html body contains <div id="root"></div>.

Sources: index.tsx:5-7, index.html:29