Diagnose and fix TwinMind common errors and exceptions.
Use when encountering transcription errors, debugging failed requests,
or troubleshooting integration issues.
Trigger with phrases like "twinmind error", "fix twinmind",
"twinmind not working", "debug twinmind", "transcription failed".
Quick reference for the most common TwinMind errors and their solutions.
Prerequisites
TwinMind extension or API configured
Access to error logs or console
API credentials for testing
Instructions
Step 1: Identify the Error
Check error message in console, extension popup, or API response.
Step 2: Find Matching Error Below
Match your error to one of the documented cases.
Step 3: Apply Solution
Follow the solution steps for your specific error.
Error Reference
Authentication Failed
Error Message:
Error: Authentication failed - Invalid or expired API key
Status: 401 Unauthorized # HTTP 401 Unauthorized
Cause: API key is missing, expired, or incorrect.
Solution:
set -euo pipefail
# Verify API key is set correctly
echo $TWINMIND_API_KEY
# Test authentication
curl -H "Authorization: Bearer $TWINMIND_API_KEY" \
https://api.twinmind.com/v1/health
# Regenerate key if expired
# Visit: https://twinmind.com/settings/api
Error: Speaker diarization failed
DiarizationError: Unable to identify distinct speakers
Cause: Single speaker, overlapping speech, or poor audio quality.
Solution:
// Retry without diarization
const transcript = await client.transcribe(audioUrl, {
diarization: false, // Disable diarization
});
// Or provide speaker count hint
const transcript = await client.transcribe(audioUrl, {
diarization: true,
expected_speakers: 3, // Help the model
});
Calendar Sync Failed
Error Message:
Error: Calendar sync failed
OAuth2Error: Token expired or revoked
Cause: Google/Microsoft OAuth token expired.
Solution:
1. Open TwinMind extension
2. Go to Settings > Integrations
3. Click "Disconnect" for calendar
4. Click "Connect" to re-authorize
5. Grant all requested permissions
Summary Generation Failed
Error Message:
Error: Summary generation failed
GenerationError: Transcript too short for summarization
Cause: Transcript doesn't have enough content.
Solution:
// Check transcript length before summarization
const minWordsForSummary = 50;
const wordCount = transcript.text.split(/\s+/).length;
if (wordCount < minWordsForSummary) {
console.log('Transcript too short for summary');
return null;
}
const summary = await client.summarize(transcript.id);
Cause: Extension crashed, outdated, or Chrome issue.
Solution:
1. Disable and re-enable extension:
chrome://extensions/ > TwinMind > Toggle off/on
2. Clear extension data:
Right-click extension > Manage Extensions > Clear data
3. Reinstall extension:
Remove > Visit Chrome Web Store > Reinstall
4. Check for conflicts:
Disable other extensions temporarily
Network Error
Error Message:
Error: Network request failed
TypeError: Failed to fetch
ERR_CONNECTION_REFUSED
Cause: Network connectivity issues or firewall blocking.
Solution:
set -euo pipefail
# Test API connectivity
curl -v https://api.twinmind.com/v1/health
# Check if firewall is blocking
telnet api.twinmind.com 443 # 443: HTTPS port
# Test with different DNS
curl --resolve api.twinmind.com:443:$(dig +short api.twinmind.com) \ # HTTPS port
https://api.twinmind.com/v1/health
Quick Diagnostic Commands
set -euo pipefail
# Check TwinMind API status
curl -s api/v2/status.json | jq '.status'
# Verify API connectivity
curl -I https://api.twinmind.com/v1/health
# Test authentication
curl -H "Authorization: Bearer $TWINMIND_API_KEY" \
https://api.twinmind.com/v1/me
# Check local environment
env | grep TWINMIND
# Validate audio file
ffprobe -v error -show_format -show_streams audio.mp3
