claude-code-skills-reference/transcript-fixer/references/troubleshooting.md

Troubleshooting Guide

Solutions to common issues and error conditions.

Table of Contents

• API Authentication Errors
  • GLM_API_KEY Not Set
  • Invalid API Key
• Learning System Issues
  • No Suggestions Generated
• Database Issues
  • Database Not Found
  • Database Locked
  • Corrupted Database
  • Missing Tables
• Common Pitfalls
  • 1. Stage Order Confusion
  • 2. Overwriting Imports
  • 3. Ignoring Learned Suggestions
  • 4. Testing on Large Files
  • 5. Manual Database Edits Without Validation
  • 6. Committing .db Files to Git
• Validation Commands
  • Quick Health Check
  • Detailed Diagnostics
• Getting Help

API Authentication Errors

GLM_API_KEY Not Set

Symptom:

❌ Error: GLM_API_KEY environment variable not set
   Set it with: export GLM_API_KEY='your-key'

Solution:

# Check if key is set
echo $GLM_API_KEY

# If empty, export key
export GLM_API_KEY="your-api-key-here"

# Verify
uv run scripts/fix_transcription.py --validate

Persistence: Add to shell profile (.bashrc or .zshrc) for permanent access.

See glm_api_setup.md for detailed API key management.

Invalid API Key

Symptom: API calls fail with 401/403 errors

Solutions:

1. Verify key is correct (copy from https://open.bigmodel.cn/)
2. Check for extra spaces or quotes in the key
3. Regenerate key if compromised
4. Verify API quota hasn't been exceeded

Learning System Issues

No Suggestions Generated

Symptom: Running --review-learned shows no suggestions after multiple corrections.

Requirements:

• Minimum 3 correction runs with consistent patterns
• Learning frequency threshold ≥3 (default)
• Learning confidence threshold ≥0.8 (default)

Diagnostic steps:

# Check correction history count
sqlite3 ~/.transcript-fixer/corrections.db "SELECT COUNT(*) FROM correction_history;"

# If 0, no corrections have been run yet
# If >0 but <3, run more corrections

# Check suggestions table
sqlite3 ~/.transcript-fixer/corrections.db "SELECT * FROM learned_suggestions;"

# Check system configuration
sqlite3 ~/.transcript-fixer/corrections.db "SELECT key, value FROM system_config WHERE key LIKE 'learning%';"

Solutions:

1. Run at least 3 correction sessions
2. Ensure patterns repeat (same error → same correction)
3. Verify database permissions (should be readable/writable)
4. Check correction_history table has entries

Database Issues

Database Not Found

Symptom:

⚠️  Database not found: ~/.transcript-fixer/corrections.db

Solution:

uv run scripts/fix_transcription.py --init

This creates the database with the complete schema.

Database Locked

Symptom:

Error: database is locked

Causes:

• Another process is accessing the database
• Unfinished transaction from crashed process
• File permissions issue

Solutions:

# Check for processes using the database
lsof ~/.transcript-fixer/corrections.db

# If processes found, kill them or wait for completion

# If database is corrupted, backup and recreate
cp ~/.transcript-fixer/corrections.db ~/.transcript-fixer/corrections_backup.db
sqlite3 ~/.transcript-fixer/corrections.db "VACUUM;"

Corrupted Database

Symptom: SQLite errors, integrity check failures

Solutions:

# Check integrity
sqlite3 ~/.transcript-fixer/corrections.db "PRAGMA integrity_check;"

# If corrupted, attempt recovery
sqlite3 ~/.transcript-fixer/corrections.db ".recover" | sqlite3 ~/.transcript-fixer/corrections_new.db

# Replace database with recovered version
mv ~/.transcript-fixer/corrections.db ~/.transcript-fixer/corrections_corrupted.db
mv ~/.transcript-fixer/corrections_new.db ~/.transcript-fixer/corrections.db

Missing Tables

Symptom:

❌ Database missing tables: ['corrections', ...]

Solution: Reinitialize schema (safe, uses IF NOT EXISTS):

python -c "from core import CorrectionRepository; from pathlib import Path; CorrectionRepository(Path.home() / '.transcript-fixer' / 'corrections.db')"

Or delete database and reinitialize:

# Backup first
cp ~/.transcript-fixer/corrections.db ~/corrections_backup_$(date +%Y%m%d).db

# Reinitialize
uv run scripts/fix_transcription.py --init

Common Pitfalls

1. Stage Order Confusion

Problem: Running Stage 2 without Stage 1 output.

Solution: Use --stage 3 for full pipeline, or run stages sequentially:

# Wrong: Stage 2 on raw file
uv run scripts/fix_transcription.py --input file.md --stage 2  # ❌

# Correct: Full pipeline
uv run scripts/fix_transcription.py --input file.md --stage 3  # ✅

# Or sequential stages
uv run scripts/fix_transcription.py --input file.md --stage 1
uv run scripts/fix_transcription.py --input file_stage1.md --stage 2

2. Overwriting Imports

Problem: Using --import without --merge overwrites existing corrections.

Solution: Always use --merge flag:

# Wrong: Overwrites existing
uv run scripts/fix_transcription.py --import team.json  # ❌

# Correct: Merges with existing
uv run scripts/fix_transcription.py --import team.json --merge  # ✅

3. Ignoring Learned Suggestions

Problem: Not reviewing learned patterns, missing free optimizations.

Impact: Patterns detected by AI remain expensive (Stage 2) instead of cheap (Stage 1).

Solution: Review suggestions every 3-5 runs:

uv run scripts/fix_transcription.py --review-learned
uv run scripts/fix_transcription.py --approve "错误" "正确"

4. Testing on Large Files

Problem: Testing dictionary changes on large files wastes API quota.

Solution: Start with --stage 1 on small files (100-500 lines):

# Test dictionary changes first
uv run scripts/fix_transcription.py --input small_sample.md --stage 1

# Review output, adjust corrections
# Then run full pipeline
uv run scripts/fix_transcription.py --input large_file.md --stage 3

5. Manual Database Edits Without Validation

Problem: Direct SQL edits might violate schema constraints.

Solution: Always validate after manual changes:

sqlite3 ~/.transcript-fixer/corrections.db
# ... make changes ...
.quit

# Validate
uv run scripts/fix_transcription.py --validate

6. Committing .db Files to Git

Problem: Binary database files in Git cause merge conflicts and bloat repository.

Solution: Use JSON exports for version control:

# .gitignore
*.db
*.db-journal
*.bak

# Export for version control instead
uv run scripts/fix_transcription.py --export corrections_$(date +%Y%m%d).json
git add corrections_*.json

Validation Commands

Quick Health Check

uv run scripts/fix_transcription.py --validate

Detailed Diagnostics

# Check database integrity
sqlite3 ~/.transcript-fixer/corrections.db "PRAGMA integrity_check;"

# Check table counts
sqlite3 ~/.transcript-fixer/corrections.db "
SELECT 'corrections' as table_name, COUNT(*) as count FROM corrections
UNION ALL
SELECT 'context_rules', COUNT(*) FROM context_rules
UNION ALL
SELECT 'learned_suggestions', COUNT(*) FROM learned_suggestions
UNION ALL
SELECT 'correction_history', COUNT(*) FROM correction_history;
"

# Check configuration
sqlite3 ~/.transcript-fixer/corrections.db "SELECT * FROM system_config;"

Getting Help

If issues persist:

1. Run --validate to collect diagnostic information
2. Check correction_history and audit_log tables for errors
3. Review references/file_formats.md for schema details
4. Check references/architecture.md for component details
5. Verify Python and uv versions are up to date

For database corruption, automatic backups are created before migrations. Check for .bak files in ~/.transcript-fixer/.