Usage Issues

This document compiles common problems and solutions encountered when using CueMate features.

Tip

If you cannot find an answer to your problem here, check the Feature Guide for more detailed feature descriptions.

1. macOS Platform

1.1 Inaccurate Speech Recognition

Problem Description: When using speech recognition, the transcribed text doesn't match the actual spoken content, or there are many errors.

Key Factors for Improving Recognition Accuracy

Environment > Device > Pronunciation > Configuration

The most important factors are ensuring a quiet environment and clear pronunciation, followed by device and parameter adjustments.

Optimization Suggestions:

1. Environment Optimization:

   • Choose a quiet environment, avoid background noise
   • Turn off fans, air conditioners, and other noise-producing devices
   • Avoid using in noisy public places

2. Device Adjustment:

   • Adjust microphone position, 15-20cm from mouth is optimal
   • Use external microphone, which usually has better quality than built-in
   • Ensure microphone is not blocked or covered

3. Pronunciation Tips:

   • Speak clearly, avoid mumbling
   • Moderate speed, not too fast or too slow
   • Avoid using dialects, use standard Mandarin/English

4. System Settings:

   • Enable noise suppression in Voice Settings
   • Add professional terms to custom vocabulary
   • First run Voice Test to confirm device is working

1.2 High Speech Recognition Latency

Problem Description: Long wait time after speaking before seeing recognition results, affecting user experience.

Solutions:

1. Device Optimization:

   • Use wired microphone instead of Bluetooth (Bluetooth has latency)
   • Ensure microphone connection is stable, avoid looseness

2. System Resources:

   • Close unnecessary background programs, free up CPU and memory
   • Open Docker Desktop settings, increase resources allocated to Docker
   • Recommended: 4GB+ memory, 2+ CPU cores

3. Network Check:

   • Check if network connection is stable
   • Confirm cuemate-asr service is running normally (port 10095)
   • Check Container Monitor to confirm service status

4. Service Restart:

   • Restart cuemate-asr service in Container Monitor page
   • Completely quit and restart CueMate application

1.3 Cannot Capture System Audio

Problem Description: When using speaker test or interview training, cannot recognize audio content played by speakers.

System Permission Required

Capturing system audio requires macOS "Screen Recording & System Audio" permission. Follow the steps below to check and grant permission.

macOS Solution:

1. Check Permission:

   • Open System Settings > Privacy & Security > Screen Recording & System Audio
   • Confirm CueMate is checked
   • If not checked, check it and restart CueMate

2. Permission Description:

   • "Screen Recording & System Audio" permission is only used for system audio capture
   • CueMate will NOT record screen content
   • See Voice Test - Screen Recording & System Audio Permission for details

Alternative: Using Virtual Audio Device (Advanced Users)

Use Cases: Don't want to grant screen recording permission, or system audio capture is unstable

Steps:

1. Install BlackHole or other virtual audio device
2. Route speaker output to virtual device
3. Select virtual device as input in voice settings

Recommended Tool: BlackHole - Open source free macOS virtual audio driver

1.4 Invalid API Key

Problem Description: After adding API Key in model settings, test connection shows "Invalid API Key" or "Authentication failed".

Common API Key Formats

Different platforms have different API Key formats, please note the differences:

Platform	Format Example	Length
OpenAI	sk-proj-xxxxx...	51 chars
Azure OpenAI	a1b2c3d4e5f6...	32 chars
Zhipu AI	xxxxxx.xxxxxx	Contains .
Moonshot (Kimi)	sk-xxxxx...	56 chars
Tongyi Qianwen	sk-xxxxx...	Variable

Check Steps:

1. Format Check:

   • Confirm API Key format is correct, no extra spaces
   • Avoid selecting line breaks when copying
   • Use plain text editor to check for hidden characters

2. Validity Check:

   • Confirm API Key has not expired
   • Log in to the corresponding platform to check API Key status
   • If expired, generate a new API Key

3. Account Check:

   • Confirm account balance is sufficient
   • Some platforms require recharge before using API
   • Check if there are usage limits or rate limits

4. Service Availability:

   • Check if the corresponding AI service is running normally
   • Visit official website to confirm service status
   • Try testing with another API Key

See Model Settings for details.

1.5 Test Connection Failed

Problem Description: After clicking "Test Connection" in model settings page, shows connection failed or timeout.

Troubleshooting Steps:

1. Check Network Connection:

   • Confirm network connection is normal
   • Try accessing the corresponding AI service's official website
   • Check if VPN is needed (e.g., for OpenAI)

2. Verify API URL is Correct:

   • Check if API Endpoint address is correct
   • OpenAI: https://api.openai.com/v1
   • Azure OpenAI: Need to fill in complete resource address
   • For other platforms, refer to official documentation

3. Confirm API Key is Valid:

   • Refer to issue 4 to check API Key
   • Try testing in official API tools
   • Confirm permission scope includes required models

4. View Error Logs:

   • Open Log Management page
   • View llm-router service error logs
   • Troubleshoot based on specific error messages

1.6 Slow Model Response

Problem Description: After asking AI a question, waiting a long time for response, or response speed is slow.

Model Speed Comparison (Fast → Slow)

Fastest: GPT-3.5-turbo, DeepSeek, Kimi Faster: GPT-4o-mini, Zhipu GLM-4-Flash Slower: GPT-4, Claude-3-Opus, GPT-4o

For daily use, recommend selecting "Fastest" or "Faster" level models.

Optimization Methods:

1. Adjust Model Parameters:

   • Lower max_tokens parameter (default 2000)
   • Reduce temperature value to speed up generation
   • Adjust in Model Settings

2. Change Model:

Scenario	Recommended Model	Reason
Daily conversation	GPT-3.5-turbo	Fast, low cost
Code generation	DeepSeek Coder	Professional and fast
Document analysis	Kimi (Moonshot)	Strong long text capability
Complex reasoning	GPT-4	High accuracy

3. Enable Caching (if supported):

   • Some models support caching mechanism
   • Same questions will directly return cached results
   • Check model documentation to confirm support

4. Check Network Speed:

   • Use network speed test tool to check bandwidth
   • Try switching network connection (Wi-Fi → wired)
   • When using VPN, select faster nodes

1.7 Document Upload Failed

Problem Description: When uploading documents to knowledge base, shows upload failed or processing failed.

IMPORTANT

Supported Document Formats and Limits:

• Supported formats: .txt, .md, .pdf, .docx, .doc
• Single file size: Maximum 100MB
• Not supported: Images, videos, compressed files, and other multimedia files

Possible Causes:

1. Unsupported File Format:

   • Supported formats: .txt, .md, .pdf, .docx, .doc
   • Images, videos, and other multimedia files not supported
   • Compressed files need to be extracted first

2. File Size Exceeds Limit:

   • Single file maximum 100MB
   • Recommend splitting large files into multiple smaller files
   • Or remove unnecessary content from documents

3. Insufficient Disk Space:

   • Check system disk remaining space
   • Ensure at least 1GB available space
   • Clean up unnecessary files

4. Document Content Corrupted:

   • Try regenerating the document
   • Use other tools to open document and check integrity
   • Convert to another format before uploading

Solutions:

• Convert file format to supported format
• Compress or split file size
• Clean up disk space and retry
• Check document integrity, ensure file is not corrupted

See Vector Knowledge Base for details.

1.8 Knowledge Base Retrieval Returns No Results

Problem Description: When asking AI questions, knowledge base clearly has relevant content, but retrieval returns no results.

TIP

Knowledge base retrieval effectiveness is closely related to document quantity and quality. Recommendations:

• Upload 10+ documents in relevant fields
• Document content should be detailed and structured
• Use precise professional terms when asking questions

Optimization Suggestions:

1. Upload More Relevant Documents:

   • Ensure knowledge base contains documents in relevant fields
   • Document content should cover the knowledge points being asked
   • Recommend uploading 10+ related documents to improve recall rate

2. Optimize Query Keywords:

   • Use more precise keywords
   • Avoid using overly broad words
   • Try using synonyms or related terms

3. Adjust Retrieval Parameters:

   • Adjust Top-K parameter in knowledge base settings (default 5)
   • Increasing Top-K can retrieve more related documents
   • But also increases noise, recommend adjusting gradually

4. Re-index Documents:

   • Re-index all documents in knowledge base management page
   • Delete and re-upload documents
   • Confirm vectorization process completed normally

1.9 Vectorization Failed

Problem Description: After uploading document, shows "Vectorization failed" or "Processing failed".

Check Items:

1. Document Readability:

   • Confirm document can be opened normally
   • Check if document encoding is correct (recommend UTF-8)
   • Ensure document content is not pure images or scans

2. Embedding Service Check:

   • Check Container Monitor
   • Confirm cuemate-rag-service is running normally
   • Check cuemate-chroma vector database status

3. System Resources:

   • Vectorization requires certain CPU and memory
   • Ensure sufficient system resources
   • Pause other high-load tasks

4. View Error Logs:

   • Open Log Management
   • View rag-service error logs
   • Troubleshoot based on specific error messages

1.10 Poor AI Answer Quality

Problem Description: In mock interviews or questions, AI answers are low quality, inaccurate, or irrelevant.

Improvement Methods:

1. Use Better Models:

   • Prefer high-quality models like GPT-5, Claude-4.5-Sonnet
   • Avoid using outdated or low-quality models
   • Configure in Model Settings

2. Optimize Prompts:

   • Adjust system prompts in Prompt Management
   • Provide more detailed context information
   • Specify response format and requirements

3. Improve Knowledge Base:

   • Upload more documents in relevant fields to Vector Knowledge Base
   • Ensure document content is accurate and authoritative
   • Regularly update knowledge base content

4. Adjust Model Parameters:

   • Lower temperature (0.3-0.7) for more deterministic answers
   • Increase max_tokens to allow more detailed answers
   • Adjust top_p to control answer diversity

1.11 Interview Questions Don't Match Position

Problem Description: In mock interviews, AI-generated interview questions have weak relevance to the applied position.

Solutions:

1. Complete Position Information:

   • Fill in detailed JD in Create New Position
   • Include job responsibilities, skill requirements, job content
   • More detailed information means more precise generated questions

2. Update Skill Requirements:

   • Clearly list required tech stack
   • Mark key skills to assess
   • Add special requirements or bonus items

3. Manually Select Questions:

   • Add related questions in Interview Questions
   • Mark question type and difficulty
   • Questions from the question bank will be prioritized during interviews

4. Add Custom Questions:

   • Add questions based on actual interview experience
   • Include answers and scoring criteria
   • Continuously improve the question bank

1.12 Inaccurate Interview Scoring

Problem Description: In mock interviews, AI scoring of answers doesn't match expectations, or evaluation is not objective enough.

Possible Causes:

1. Incomplete Answers:

   • Answer is too brief, missing key information
   • Didn't cover all points of the question
   • Lacks specific examples or data support

2. Model Understanding Deviation:

   • Model used has limited understanding of professional terms
   • Knowledge in certain fields is not deep enough
   • Evaluation criteria differ from human interviewers

3. Unreasonable Scoring Criteria:

   • Default scoring criteria may not apply to all scenarios
   • Different positions have different scoring focus
   • Needs targeted adjustment

Optimization Suggestions:

1. Answer All Points Completely:

   • Use STAR method (Situation-Task-Action-Result)
   • Include technical details and data support
   • Structured expression, clear hierarchy

2. Adjust Scoring Prompts:

   • Modify interview evaluation prompts in Prompt Management
   • Clarify scoring dimensions and weights
   • Provide scoring examples

3. Reference Standard Answers:

   • Add standard answers in interview questions
   • Compare your answers with standard answers
   • Continuously optimize answering methods

1.13 Data Loss

Problem Description: Interview records, conversation history, knowledge base documents, and other data suddenly lost.

Prevention Measures:

1. Regular Data Backup:

   • Enable automatic backup in system settings
   • Manually export important data
   • Recommend backing up weekly

2. Enable Automatic Backup:

   • Configure backup frequency and retention policy
   • Set backup storage location
   • Verify backup file integrity

3. Use Cloud Storage:

   • Sync backup files to cloud (iCloud, OneDrive, etc.)
   • Enable version control
   • Regularly check sync status

Recovery Methods:

1. Restore from Backup:

   • Select backup file in system settings
   • Execute data recovery operation
   • Verify restored data integrity

2. Check Recycle Bin:

   • Some delete operations first move to recycle bin
   • Check if recovery is possible
   • Recover quickly to avoid permanent deletion

3. Contact Technical Support:

   • If the above methods don't work
   • Provide detailed problem description and logs
   • Contact information at bottom of documentation

1.14 Import/Export Failed

Problem Description: When trying to import or export data, shows failed or generated file cannot be used.

Check Items:

1. File Format Check:

   • Confirm file format is correct when importing
   • Supported formats: JSON, CSV (depending on function)
   • File not corrupted or modified

2. File Integrity:

   • Check if file size is normal
   • Use text editor to view file content
   • Confirm JSON format is correct, no syntax errors

3. Permission Check:

   • Open System Settings > Privacy & Security > Files and Folders
   • Confirm CueMate has permission to access corresponding folders
   • If not, click "+" to add permission

4. Disk Space:

   • Ensure sufficient disk space when exporting
   • Recommend at least 1GB available space
   • Clean up temporary files

1.15 Microphone/Speaker Not Detected

Problem Description: In voice settings or voice test page, cannot see microphone or speaker devices.

Solutions:

1. Check Device Connection:

   • Confirm device is properly connected to computer
   • Try unplugging and reconnecting device
   • Check if device works normally (test in other applications)

2. Check System Settings:

   • Open System Settings > Sound
   • Switch to Input tab to view microphones
   • Switch to Output tab to view speakers
   • Confirm device is in list and set as default device

3. Refresh Device List:

   • Click refresh button on device selection dropdown
   • Or restart CueMate application
   • Devices will be automatically rescanned

4. Check Permissions:

   • Open System Settings > Privacy & Security > Microphone
   • Confirm CueMate is checked

See Voice Settings for details.

1.16 Service Startup Failed

Problem Description: In Container Monitor page, some services show status as "Stopped" or "Error".

Solutions:

1. View Service Status:

   • Open Container Monitor
   • Check status of all 6 services
   • Record names of abnormal services

2. View Error Logs:

   • Click "Logs" button for abnormal service
   • View recent error messages
   • Take screenshots for troubleshooting

3. Restart Service:

   • Click "Restart" button for abnormal service
   • Wait for service restart to complete (about 30 seconds)
   • Refresh page to check status

4. Check Dependent Services:

   • Some services depend on other services
   • Ensure Docker Desktop is running normally
   • Check if ports are occupied

See Container Monitor - FAQ for details.

1.17 Control Bar Cannot Operate

Problem Description: Clicking buttons on floating control bar has no response, or control bar cannot be dragged.

Solutions:

1. Check Interaction Mode:

   • Click "Interaction Mode" button on control bar
   • Confirm in "Interactive" mode (icon highlighted)
   • Control bar cannot be clicked in "Pass-through" mode

2. Restart Application:

   • Completely quit CueMate (menu bar > Quit)
   • Restart application
   • Check if control bar is back to normal

3. Check Service Status:

   • Some buttons depend on backend services
   • Open Container Monitor
   • Confirm all services are running normally

4. Reset Window Position:

   • Reset window position in system settings
   • Control bar will return to default position
   • Drag to appropriate position again

1.18 License Activation Failed

Problem Description: After entering license key, shows activation failed or key invalid.

Solutions:

1. Check Key Format:

   • Confirm key format is correct, no extra spaces
   • Avoid missing characters when copying and pasting
   • Check for special characters

2. Check Validity Period:

   • Confirm license has not expired
   • Log in to license management backend to check status
   • If expired, need to renew

3. Check Activation Count:

   • License may have device limit
   • Unbind old devices in license management backend
   • Re-activate current device

4. Network Connection:

   • Activation needs to connect to license server
   • Check if network connection is normal
   • Retry later or contact technical support

See License Management for details.

1.19 Log Files Too Large

Problem Description: Log files occupy large amount of disk space, causing insufficient disk space.

Solutions:

1. Clean Old Logs:

   • Open Log Management
   • Select date range
   • Batch delete old log files

2. Adjust Log Level:

   • Lower log level in system settings
   • Recommend WARN or ERROR level for production environment
   • Avoid long-term use of DEBUG level

3. Enable Log Rotation:

   • Configure automatic log rotation policy
   • Set single log file size limit
   • Set log retention days (e.g., 7 days)

4. Regular Cleanup:

   • Recommend cleaning logs weekly
   • Or configure automatic cleanup task
   • Keep only logs from last 3-7 days

1.20 Application Update Failed

Problem Description: After detecting new version, update download or installation fails.

Solutions:

1. Check Network Connection:

   • Confirm network connection is stable
   • Downloading large files (about 5GB) requires stable network
   • Avoid using unstable Wi-Fi

2. Check Disk Space:

   • Ensure at least 10GB available space
   • Update needs to download new version and extract
   • Clean up disk and retry

3. Manual Download Update:

   • Visit official website to download latest version
   • Or download from Baidu Netdisk/GitHub
   • Manually install update package

4. View Update Logs:

   • Open Log Management
   • View error messages during update process
   • Troubleshoot based on error messages

See Version Upgrade for details.

2. Windows Platform

Under Development

Windows version is under development, stay tuned.

If you have any suggestions or requirements for the Windows version, please provide feedback through:

• GitHub Issues: https://github.com/cuemate-chat/cuemate/issues
• Email: nuneatonhydroplane@gmail.com

Get More Help

If the above methods cannot solve your problem, you can get help through:

View Documentation

• Feature Guide - Detailed feature usage instructions
• Model Configuration - Large language model configuration guide
• Installation Issues - Installation related issues
• FAQ Overview - More common questions

Contact Technical Support

• GitHub Issues: https://github.com/cuemate-chat/cuemate/issues
• Email: nuneatonhydroplane@gmail.com

When submitting issues, please provide:

1. CueMate version number
2. Operating system version
3. Detailed problem description and screenshots
4. Related error logs
5. Solutions you have already tried