FAQ

This chapter collects common questions and solutions encountered during the use of CueMate. All FAQs use a numbered format (1-100) for easy cross-version updates and quick issue location.

Windows Version Under Development

The current FAQ primarily targets the macOS platform. The Windows version is under development, and relevant documentation will be updated subsequently.

1.1 Installation Issues (20 Questions)

Covers all common issues during CueMate installation, including:

Docker Installation & Configuration (Q1-Q6): Docker Desktop installation, startup failure, resource configuration, network issues
System Permission Configuration (Q7-Q9): macOS/Windows permissions, file access, security policies
Service Deployment Issues (Q10-Q15): Port conflicts, image pulling, service startup, health checks
Desktop Application Installation (Q16-Q20): .dmg/.exe installation, dependency issues, update failures

See: Complete Installation FAQ →

1.2 Usage Issues (20 Questions)

Answers common confusions during CueMate feature usage, including:

Speech Recognition (Q1-Q3): Recognition accuracy, latency issues, system audio capture
Model Configuration (Q4-Q6): API Key setup, model connection, response speed optimization
Knowledge Base Features (Q7-Q9): Document upload, retrieval results, vectorization issues
Interview Training (Q10-Q12): AI answer quality, question matching, scoring system
Other Features (Q13-Q20): Data management, import/export, device recognition, service configuration

See: Complete Usage FAQ →

1.3 Troubleshooting (20 Questions)

Provides diagnosis and solutions for system-level issues, including:

Service Issues (Q1-Q3): Service unresponsive, frequent crashes, database connection
Performance Optimization (Q4-Q7): Slow response, CPU/memory/disk usage
Network Issues (Q8-Q9): External API connection, WebSocket communication
System Configuration (Q10-Q16): Permission issues, port occupation, image issues, configuration changes
Data Management & Monitoring (Q17-Q20): Backup scripts, recovery process, health checks, performance monitoring

See: Complete Troubleshooting FAQ →

2. Top 15 Popular Issues

Platform Notes

The following answers primarily target the macOS platform. Some issues mention Windows platform operations, but please note that the Windows version is currently still under development, and this content is for reference only.

Official Windows version documentation will be updated subsequently. If you have suggestions for the Windows version, feel free to provide feedback via GitHub Issues.

2.1 Docker Desktop Cannot Start or Installation Failed?

Problem Scenario: Docker Desktop cannot start after download and installation, or the status is abnormal after startup.

Quick Solutions:

macOS:

bash

# Check if virtualization is enabled
sysctl kern.hv_support

# Reset Docker Desktop
rm -rf ~/Library/Group\ Containers/group.com.docker
rm -rf ~/Library/Containers/com.docker.docker

Windows:

powershell

# Ensure WSL 2 is installed
wsl --install
wsl --set-default-version 2

See: Installation Issues

2.2 Inaccurate Speech Recognition with Errors?

Problem Scenario: When using the speech recognition feature, the transcribed text does not match the actual spoken content.

Quick Optimization:

Choose a quiet environment to avoid background noise
Check microphone permissions (System Preferences > Privacy & Security > Microphone)
Adjust microphone distance (15-30cm is optimal)
Add professional terms to custom vocabulary
Adjust CueMate-ASR model parameters (hotword weight, VAD sensitivity)

See: Usage Issues | Voice Test Feature

2.3 API Key Configuration Failed or Error?

Problem Scenario: After configuring the API Key in settings, calling the AI model fails or has no response.

Troubleshooting Steps:

bash

# 1. Check LLM Router service logs
docker logs cuemate-llm-router

# 2. Test API connection
curl -X POST http://localhost:3002/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4","messages":[{"role":"user","content":"test"}]}'

# 3. Check API Key validity (using OpenAI as example)
curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"

See: Usage Issues

2.4 Service Startup Failed, Docker Container Cannot Run?

Problem Scenario: Services cannot start normally after executing bash private/start.sh.

Diagnostic Commands:

bash

# Check all container statuses
docker ps -a

# View failed container logs
docker logs cuemate-web-api
docker logs cuemate-llm-router

# Check port occupation
lsof -i :3001,3002,3003,3004,8000,10095

# Check Docker resources
docker system df

See: Installation Issues

2.5 High System Resource Usage (CPU/Memory)?

Problem Scenario: CPU or memory usage remains excessively high after running CueMate, affecting system performance.

Optimization Solutions:

bash

# 1. Adjust Docker resource limits (macOS)
# Docker Desktop > Settings > Resources
# CPU: 4 cores → 2 cores
# Memory: 8GB → 4GB

# 2. Use smaller models
# Web Settings > AI Models > Select gpt-4o-mini (instead of gpt-4)

# 3. Clean Docker resources
docker system prune -a --volumes

# 4. Monitor resource usage
docker stats

See: Troubleshooting

2.6 Knowledge Base Retrieval Returns No Results or Irrelevant Results?

Problem Scenario: Documents have been uploaded to the knowledge base, but no relevant content is retrieved when asking questions.

Troubleshooting:

bash

# 1. Check ChromaDB service status
curl http://localhost:8000/api/v1/heartbeat

# 2. View RAG Service logs
docker logs cuemate-rag-service

# 3. Check if vectorization is complete
# Web > Knowledge Base > Document List > Status should be "Completed"

# 4. Test retrieval API
curl -X POST http://localhost:3003/search \
  -H "Content-Type: application/json" \
  -d '{"query":"test query","top_k":5}'

See: Usage Issues

2.7 Port Conflict, Service Cannot Bind to Port?

Problem Scenario: When starting services, a message indicates ports are already in use (3001, 3002, 3003, 3004, 8000, 10095).

Solution Steps:

bash

# 1. Find processes occupying ports
lsof -i :3001
lsof -i :3004

# 2. Stop processes occupying ports
kill -9 <PID>

# 3. Or modify CueMate's ports
# Edit infra/docker/docker-compose.yml
# Modify ports mapping (e.g., 3004:3004 to 8080:3004)

See: Installation Issues | Troubleshooting

2.8 Image Pull Failed or Slow?

Problem Scenario: Error or extremely slow download speed when executing docker compose pull.

Solutions:

bash

# 1. Configure Docker mirror accelerator
# Docker Desktop > Settings > Docker Engine
# Add the following configuration:
{
  "registry-mirrors": [
    "https://docker.mirrors.ustc.edu.cn",
    "https://hub-mirror.c.163.com"
  ]
}

# 2. Use Alibaba Cloud image repository
export VERSION=v0.1.0
docker pull registry.cn-beijing.aliyuncs.com/cuemate/cuemate-web:$VERSION

# 3. Manually import images (from local file)
docker load -i cuemate-images.tar

See: Installation Issues | Troubleshooting

2.9 Data Loss or Database Corruption?

Problem Scenario: History conversations, knowledge base documents, or configurations are lost, or database errors are reported.

Recovery Steps:

bash

# 1. Stop all services
cd /Applications/CueMate.app/Contents/Resources/app.asar.unpacked/resources/config
docker compose down

# 2. Check data file integrity
ls -lh ~/Library/Application\ Support/cuemate-desktop-client/data/sqlite/
ls -lh ~/Library/Application\ Support/cuemate-desktop-client/data/chroma/

# 3. Restore from backup
tar -xzf cuemate_backup_20260115.tar.gz
cp -r sqlite_20260115/* ~/Library/Application\ Support/cuemate-desktop-client/data/sqlite/
cp -r chroma_20260115/* ~/Library/Application\ Support/cuemate-desktop-client/data/chroma/

# 4. Restart services
docker compose up -d

See: Troubleshooting

2.10 Poor AI Answer Quality or Irrelevant Responses?

Problem Scenario: AI-generated answers are inaccurate, irrelevant, or of low quality.

Optimization Suggestions:

Improve Model Quality:
- Use more powerful models (gpt-4 > gpt-4o-mini > gpt-3.5-turbo)
- Add relevant documents to knowledge base for more context
Optimize Prompts:
- Web Settings > AI Configuration > System Prompt
- Add specific answer requirements and format instructions
Adjust Retrieval Parameters:
- Increase number of retrieved documents (top_k: 3 → 5)
- Adjust similarity threshold (threshold: 0.7 → 0.6)

See: Usage Issues

2.11 Desktop Application Cannot Install or Start?

Problem Scenario: macOS/Windows desktop application installation fails or crashes after opening.

macOS:

bash

# 1. Allow unsigned applications (temporary)
sudo xattr -rd com.apple.quarantine /Applications/CueMate.app

# 2. Check permissions
System Preferences > Privacy & Security > General > Allow apps from unidentified developers

# 3. View application logs
tail -f ~/Library/Application\ Support/cuemate-desktop-client/data/logs/desktop-client/$(date +%Y-%m-%d)/error.log

Windows:

Right-click .exe > Properties > Compatibility > Run as administrator
Turn off Windows Defender or add to whitelist

See: Installation Issues

2.12 WebSocket Connection Failed, Real-time Features Unavailable?

Problem Scenario: Voice recognition, real-time messages, and other features are unavailable, with WebSocket connection errors.

Diagnostic Steps:

bash

# 1. Check CueMate-ASR service status
docker logs cuemate-asr

# 2. Test WebSocket connection
wscat -c ws://localhost:10095

# 3. Check firewall settings
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --getglobalstate

# 4. View network logs
docker logs cuemate-web-api | grep WebSocket

See: Troubleshooting | Usage Issues

2.13 Configuration File Changes Not Taking Effect?

Problem Scenario: Configuration files (docker-compose.yml, .env, etc.) have been modified, but service behavior has not changed.

Solutions:

bash

# 1. Reload configuration and restart services
cd /Applications/CueMate.app/Contents/Resources/app.asar.unpacked/resources/config
docker compose down
docker compose up -d

# 2. Force rebuild images (production environment through application update)
# Please download new version installation package and reinstall

# 3. Clear cache
docker system prune -a

# 4. Verify configuration is effective
docker exec cuemate-web-api env | grep YOUR_CONFIG

See: Troubleshooting

2.14 Application Update Failed or Version Rollback?

Problem Scenario: Desktop application automatic update fails, or issues occur after update requiring rollback.

Handling Steps:

bash

# 1. Manually download latest version
# Visit https://github.com/cuemate-chat/cuemate/releases

# 2. Clean old version data (optional)
rm -rf ~/Library/Application\ Support/cuemate-desktop-client/updates/

# 3. Roll back to old version
# Restore old version CueMate.app from backup
cp -r ~/backup/CueMate.app /Applications/

# 4. View update logs
tail -f ~/Library/Application\ Support/cuemate-desktop-client/data/logs/updater/*/info.log

See: Installation Issues | Usage Issues

2.15 How to Regularly Backup Data and Monitor System Health?

Problem Scenario: Need regular automatic data backups and system status monitoring.

Automation Scripts:

Backup Script (~/cuemate-backup.sh):

bash

#!/bin/bash
BACKUP_DIR=~/backup/cuemate
DATE=$(date +%Y%m%d_%H%M%S)
DATA_DIR=~/Library/Application\ Support/cuemate-desktop-client/data

mkdir -p $BACKUP_DIR
cd $BACKUP_DIR

# Backup database and configuration
cp -r "$DATA_DIR/sqlite" "sqlite_$DATE"
cp -r "$DATA_DIR/chroma" "chroma_$DATE"
cp -r "$DATA_DIR/config" "config_$DATE"

# Compress backup
tar -czf "cuemate_backup_$DATE.tar.gz" "sqlite_$DATE" "chroma_$DATE" "config_$DATE"

# Clean temporary files
rm -rf "sqlite_$DATE" "chroma_$DATE" "config_$DATE"

# Keep backups from last 7 days
find $BACKUP_DIR -name "cuemate_backup_*.tar.gz" -mtime +7 -delete

Scheduled Task (crontab):

bash

# Automatic backup at 2 AM daily
0 2 * * * /bin/bash ~/cuemate-backup.sh

See: Troubleshooting

Getting Help

If the above content cannot solve your problem:

Send email to: nuneatonhydroplane@gmail.com
Join community discussion: GitHub Discussions
Submit bug report: GitHub Issues
View complete documentation: CueMate Documentation

Feedback

We highly value your feedback. Please let us know through the following methods:

Documentation improvement suggestions
New feature requests
User experience feedback
Bug reports

Model Settings

FAQ

1. Quick Navigation

1.1 Installation Issues (20 Questions)

1.2 Usage Issues (20 Questions)

1.3 Troubleshooting (20 Questions)

2. Top 15 Popular Issues

2.1 Docker Desktop Cannot Start or Installation Failed?

2.2 Inaccurate Speech Recognition with Errors?

2.3 API Key Configuration Failed or Error?

2.4 Service Startup Failed, Docker Container Cannot Run?

2.5 High System Resource Usage (CPU/Memory)?

2.6 Knowledge Base Retrieval Returns No Results or Irrelevant Results?

2.7 Port Conflict, Service Cannot Bind to Port?

2.8 Image Pull Failed or Slow?

2.9 Data Loss or Database Corruption?

2.10 Poor AI Answer Quality or Irrelevant Responses?

2.11 Desktop Application Cannot Install or Start?

2.12 WebSocket Connection Failed, Real-time Features Unavailable?

2.13 Configuration File Changes Not Taking Effect?

2.14 Application Update Failed or Version Rollback?

2.15 How to Regularly Backup Data and Monitor System Health?

Getting Help

Feedback

FAQ ​

1. Quick Navigation ​

1.1 Installation Issues (20 Questions) ​

1.2 Usage Issues (20 Questions) ​

1.3 Troubleshooting (20 Questions) ​

2. Top 15 Popular Issues ​

2.1 Docker Desktop Cannot Start or Installation Failed? ​

2.2 Inaccurate Speech Recognition with Errors? ​

2.3 API Key Configuration Failed or Error? ​

2.4 Service Startup Failed, Docker Container Cannot Run? ​

2.5 High System Resource Usage (CPU/Memory)? ​

2.6 Knowledge Base Retrieval Returns No Results or Irrelevant Results? ​

2.7 Port Conflict, Service Cannot Bind to Port? ​

2.8 Image Pull Failed or Slow? ​

2.9 Data Loss or Database Corruption? ​

2.10 Poor AI Answer Quality or Irrelevant Responses? ​

2.11 Desktop Application Cannot Install or Start? ​

2.12 WebSocket Connection Failed, Real-time Features Unavailable? ​

2.13 Configuration File Changes Not Taking Effect? ​

2.14 Application Update Failed or Version Rollback? ​

2.15 How to Regularly Backup Data and Monitor System Health? ​

Getting Help ​

Feedback ​

FAQ

1. Quick Navigation

1.1 Installation Issues (20 Questions)

1.2 Usage Issues (20 Questions)

1.3 Troubleshooting (20 Questions)

2. Top 15 Popular Issues

2.1 Docker Desktop Cannot Start or Installation Failed?

2.2 Inaccurate Speech Recognition with Errors?

2.3 API Key Configuration Failed or Error?

2.4 Service Startup Failed, Docker Container Cannot Run?

2.5 High System Resource Usage (CPU/Memory)?

2.6 Knowledge Base Retrieval Returns No Results or Irrelevant Results?

2.7 Port Conflict, Service Cannot Bind to Port?

2.8 Image Pull Failed or Slow?

2.9 Data Loss or Database Corruption?

2.10 Poor AI Answer Quality or Irrelevant Responses?

2.11 Desktop Application Cannot Install or Start?

2.12 WebSocket Connection Failed, Real-time Features Unavailable?

2.13 Configuration File Changes Not Taking Effect?

2.14 Application Update Failed or Version Rollback?

2.15 How to Regularly Backup Data and Monitor System Health?

Getting Help

Feedback