Skip to content

Common Issues

Jump to bottom
Eric Fitzgerald edited this page Nov 12, 2025 · 1 revision

Common Issues

This page provides solutions to frequently encountered problems with TMI deployment and operation.

Authentication Problems

OAuth Login Fails

Symptoms:

  • Redirect to OAuth provider fails
  • "Invalid client" error from provider
  • Callback fails with 400/500 error

Common Causes:

  1. Incorrect Client ID/Secret: Credentials don't match provider configuration
  2. Wrong Callback URL: Callback URL mismatch between TMI config and provider
  3. Provider Not Enabled: OAuth provider not configured in TMI
  4. Network Issues: Cannot reach OAuth provider

Solutions:

# Verify OAuth configuration
grep -i oauth config-*.yml

# Check environment variables
echo $GITHUB_CLIENT_ID
echo $GITHUB_CLIENT_SECRET

# Test provider reachability
curl -I https://github.com/login/oauth/authorize

# Check TMI OAuth endpoints
curl http://localhost:8080/auth/github/login

Configuration Fix:

# In config-production.yml
oauth:
  providers:
    - name: github
      client_id: "your_client_id_here"
      client_secret: "your_client_secret_here"
      callback_url: "https://yourdomain.com/auth/github/callback"
      enabled: true

See Setting-Up-Authentication for complete OAuth setup.

JWT Token Invalid or Expired

Symptoms:

  • API returns 401 Unauthorized
  • "Token expired" error message
  • Need to re-authenticate frequently

Common Causes:

  1. Token has expired (default: 24 hours)
  2. JWT secret changed on server
  3. Token not included in request
  4. Malformed Authorization header

Solutions:

# Check token expiration
# Decode JWT at https://jwt.io or:
echo "YOUR_TOKEN" | cut -d'.' -f2 | base64 -d 2>/dev/null | jq .exp

# Verify Authorization header format
curl -H "Authorization: Bearer YOUR_TOKEN" http://localhost:8080/api/v1/threat-models

# Re-authenticate to get new token
curl http://localhost:8080/auth/github/login

Prevention:

  • Implement token refresh logic in clients
  • Increase token lifetime if appropriate (trade-off with security)
  • Store tokens securely and check expiration before use

JWT Secret Mismatch

Symptoms:

  • All authentication fails after server restart
  • "Invalid signature" errors
  • Previously valid tokens rejected

Cause: JWT_SECRET changed or not set consistently

Solution:

# Ensure JWT_SECRET is set consistently
export JWT_SECRET="your-long-random-secret-256-bits"

# Or set in config
echo "jwt_secret: your-long-random-secret-256-bits" >> config-production.yml

# Restart server
./bin/tmiserver

Important: Changing JWT_SECRET invalidates all existing tokens. Users must re-authenticate.

Connection Issues

Cannot Connect to Database

Symptoms:

  • "connection refused" errors
  • "password authentication failed"
  • Server fails to start with database errors

Diagnosis:

# Check if PostgreSQL is running
pg_isready -h localhost -p 5432

# Test connection with psql
psql -h localhost -U postgres -d tmi

# Check TMI database configuration
grep -i db_ config-*.yml

# View database logs
docker logs tmi-postgres  # if using Docker
tail -f /var/log/postgresql/postgresql-*.log

Common Causes & Solutions:

  1. PostgreSQL not running:

    # Start PostgreSQL
make start-postgres
# Or with Docker
docker start tmi-postgres

  2. Wrong credentials:

    # Verify environment variables
echo $DB_USERNAME
echo $DB_PASSWORD

# Update configuration
export DB_USERNAME=postgres
export DB_PASSWORD=your_password

  3. Wrong host/port:

    # Check database is listening
netstat -an | grep 5432

# Update configuration
export DB_HOST=localhost
export DB_PORT=5432

  4. Database doesn't exist:

    # Create database
createdb -U postgres tmi

# Run migrations
./bin/migrate up

See Database-Setup for database configuration details.

Cannot Connect to Redis

Symptoms:

  • "connection refused" to Redis
  • WebSocket features not working
  • Real-time collaboration fails

Diagnosis:

# Check if Redis is running
redis-cli ping

# Test connection
redis-cli -h localhost -p 6379 INFO

# Check TMI Redis configuration
grep -i redis config-*.yml

Solutions:

  1. Redis not running:

    # Start Redis
make start-redis
# Or with Docker
docker start tmi-redis

  2. Wrong host/port:

    # Update configuration
export REDIS_HOST=localhost
export REDIS_PORT=6379

# Or in config file
redis:
  host: localhost
  port: 6379

  3. Redis requires password:

    # Test with password
redis-cli -a yourpassword ping

# Configure in TMI
export REDIS_PASSWORD=yourpassword

See Configuration-Reference for Redis configuration options.

Port Already in Use

Symptoms:

  • "address already in use" error
  • Server fails to start
  • Cannot bind to port 8080

Diagnosis:

# Check what's using the port
lsof -i :8080
netstat -an | grep 8080

# Find process ID
ps aux | grep tmiserver

Solutions:

  1. Kill conflicting process:

    # Find and kill process
lsof -ti :8080 | xargs kill -9

  2. Change TMI port:

    # Use different port
export SERVER_PORT=9090
./bin/tmiserver

  3. Check for duplicate instances:

    # List all tmiserver processes
ps aux | grep tmiserver

# Kill all instances
pkill tmiserver

WebSocket Problems

WebSocket Connection Fails

Symptoms:

  • Real-time updates not working
  • "WebSocket connection failed" in browser console
  • Diagram edits not synchronizing

Common Causes:

  1. TLS Mismatch:

    • Using ws:// with HTTPS site (should be wss://)
    • Using wss:// with HTTP site (should be ws://)

  2. Firewall/Proxy Blocking:

    • Corporate firewall blocks WebSocket
    • Proxy doesn't support WebSocket upgrade

  3. Redis Connection Issues:

    • Redis not running
    • Redis connection dropped

Solutions:

  1. Fix TLS mismatch:

    // In web client configuration
const wsUrl = window.location.protocol === 'https:'
  ? 'wss://api.example.com/ws'
  : 'ws://api.example.com/ws';

  2. Check browser console:

    • Open Developer Tools (F12)
    • Check Console tab for WebSocket errors
    • Check Network tab for WebSocket handshake

  3. Test WebSocket directly:

    # Use websocat or wscat
websocat wss://api.example.com/ws

# Check server logs
grep -i websocket logs/tmi.log

  4. Verify Redis:

    # Check Redis is running
redis-cli ping

# Check Redis connections
redis-cli CLIENT LIST | grep websocket

See Debugging-Guide#websocket-debugging for detailed WebSocket troubleshooting.

WebSocket Disconnects Frequently

Symptoms:

  • Connection drops every few minutes
  • "Connection lost" messages
  • Need to refresh frequently

Common Causes:

  1. Proxy timeout
  2. Load balancer timeout
  3. Redis connection issues
  4. Network instability

Solutions:

  1. Increase proxy timeout:

    # Nginx example
location /ws {
    proxy_read_timeout 3600s;
    proxy_send_timeout 3600s;
}

  2. Implement reconnection logic:

    // Client-side reconnection
socket.onclose = function() {
    setTimeout(connectWebSocket, 1000);
};

  3. Check Redis stability:

    # Monitor Redis
redis-cli MONITOR

# Check Redis memory
redis-cli INFO memory

Database Issues

Migration Fails

Symptoms:

  • "migration failed" error
  • Database schema out of sync
  • Missing tables or columns

Diagnosis:

# Check migration status
./bin/migrate version

# List available migrations
ls -la auth/migrations/

# Check database schema
psql -d tmi -c "\dt"

Solutions:

  1. Run migrations:

    # Apply all pending migrations
./bin/migrate up

# Apply specific migration
./bin/migrate up 005

  2. Migration fails midway:

    # Check migration state
psql -d tmi -c "SELECT * FROM schema_migrations"

# Force migration version (use carefully!)
./bin/migrate force <version>

# Try again
./bin/migrate up

  3. Start fresh (development only):

    # WARNING: Destroys all data!
./bin/migrate drop
./bin/migrate up

See Database-Operations#migrations for migration procedures.

Database Performance Issues

Symptoms:

  • Slow query responses
  • API timeouts
  • High database CPU/memory usage

Diagnosis:

-- Find slow queries
SELECT pid, query, query_start, state_change - query_start AS duration
FROM pg_stat_activity
WHERE state = 'active'
ORDER BY duration DESC;

-- Check table sizes
SELECT schemaname, tablename,
       pg_size_pretty(pg_total_relation_size(schemaname||'.'||tablename)) AS size
FROM pg_tables
WHERE schemaname = 'public'
ORDER BY pg_total_relation_size(schemaname||'.'||tablename) DESC;

-- Check missing indexes
SELECT schemaname, tablename, attname, n_distinct, correlation
FROM pg_stats
WHERE schemaname = 'public' AND n_distinct > 100
ORDER BY n_distinct DESC;

Solutions:

  • Add indexes on frequently queried columns
  • Optimize queries with EXPLAIN ANALYZE
  • Increase database connection pool size
  • Scale database resources

See Performance-Troubleshooting#database-performance for detailed optimization.

Performance Problems

High Memory Usage

Symptoms:

  • Server using excessive RAM
  • Out of memory errors
  • Slow performance

Diagnosis:

# Check memory usage
free -h
top -o MEM

# Check process memory
ps aux --sort=-%mem | head -10

# Check Redis memory
redis-cli INFO memory

Solutions:

  1. Redis memory issues:

    # Check Redis keys
redis-cli DBSIZE

# Set maxmemory limit
redis-cli CONFIG SET maxmemory 2gb
redis-cli CONFIG SET maxmemory-policy allkeys-lru

# Clean up expired keys
redis-cli --scan --pattern "*" | xargs redis-cli DEL

  2. Application memory leaks:

    • Check for goroutine leaks: /debug/pprof/goroutine
    • Profile memory: /debug/pprof/heap
    • Restart server to clear

  3. Database connection pool:

    # Reduce connection pool size
export DB_MAX_CONNECTIONS=10
export DB_MAX_IDLE_CONNECTIONS=5

See Performance-Troubleshooting for comprehensive performance tuning.

Slow API Responses

Symptoms:

  • API requests take multiple seconds
  • Timeouts
  • Poor user experience

Diagnosis:

# Test API response time
time curl http://localhost:8080/api/v1/threat-models

# Check server logs for slow queries
grep "duration=[5-9][0-9][0-9]" logs/tmi.log

# Profile API endpoints
curl http://localhost:8080/debug/pprof/profile?seconds=30 > profile.out
go tool pprof profile.out

Solutions:

  • Optimize database queries
  • Add caching with Redis
  • Increase server resources
  • Scale horizontally with load balancer

See Performance-and-Scaling for scaling strategies.

Configuration Issues

Configuration Not Loading

Symptoms:

  • Server uses default values
  • Environment variables ignored
  • YAML config not applied

Diagnosis:

# Check config file location
ls -la config-*.yml

# Verify environment variables
env | grep TMI
env | grep DB_
env | grep REDIS_

# Check server startup logs
grep -i "loading configuration" logs/tmi.log

Solutions:

  1. Specify config file:

    # Set config file path
export CONFIG_FILE=config-production.yml
./bin/tmiserver

# Or use flag
./bin/tmiserver -config config-production.yml

  2. Environment variable precedence:

    • Environment variables override YAML config
    • Use unset VAR to remove env var
    • Check for typos in variable names

  3. YAML syntax errors:

    # Validate YAML
yamllint config-production.yml

# Or use Python
python -c "import yaml; yaml.safe_load(open('config-production.yml'))"

See Configuration-Reference for complete configuration guide.

TLS/HTTPS Not Working

Symptoms:

  • Browser shows "Not Secure"
  • Certificate errors
  • Unable to connect via HTTPS

Diagnosis:

# Check TLS configuration
grep -i tls config-*.yml
echo $TLS_ENABLED
echo $TLS_CERT_FILE

# Verify certificate files exist
ls -la /path/to/cert.pem
ls -la /path/to/key.pem

# Test certificate
openssl x509 -in /path/to/cert.pem -text -noout

# Test HTTPS connection
curl -v https://localhost:8443

Solutions:

  1. Enable TLS:

    export TLS_ENABLED=true
export TLS_CERT_FILE=/etc/tmi/cert.pem
export TLS_KEY_FILE=/etc/tmi/key.pem

  2. Certificate issues:

    # Generate self-signed cert (development)
openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes

# Use Let's Encrypt (production)
certbot certonly --standalone -d api.example.com

  3. Certificate permissions:

    # Fix file permissions
chmod 600 /etc/tmi/key.pem
chmod 644 /etc/tmi/cert.pem
chown tmi:tmi /etc/tmi/*.pem

See Configuration-Reference#tls-configuration for TLS setup.

Docker/Container Issues

Container Won't Start

Symptoms:

  • docker run fails immediately
  • Container status is "Exited"
  • No logs produced

Diagnosis:

# Check container status
docker ps -a

# View container logs
docker logs tmi-server

# Inspect container
docker inspect tmi-server

# Check for port conflicts
docker ps | grep 8080

Solutions:

  1. Port conflict:

    # Use different port
docker run -p 9090:8080 tmi-server

  2. Environment variables:

    # Pass environment variables
docker run -e DB_HOST=host.docker.internal \
           -e REDIS_HOST=host.docker.internal \
           tmi-server

  3. Volume mount issues:

    # Fix volume permissions
chmod -R 755 /path/to/data

# Mount volume
docker run -v /path/to/data:/data tmi-server

Container Network Issues

Symptoms:

  • Container cannot reach database
  • Container cannot reach Redis
  • Services cannot communicate

Solutions:

  1. Use Docker network:

    # Create network
docker network create tmi-network

# Run containers on same network
docker run --network tmi-network --name postgres postgres:15
docker run --network tmi-network --name redis redis:7
docker run --network tmi-network -e DB_HOST=postgres -e REDIS_HOST=redis tmi-server

  2. Use host networking (Linux only):

    docker run --network host tmi-server

  3. Use host.docker.internal (Mac/Windows):

    docker run -e DB_HOST=host.docker.internal \
           -e REDIS_HOST=host.docker.internal \
           tmi-server

Quick Reference

Health Check Commands

# Overall system health
make status

# Database connectivity
make db-ping

# Redis connectivity
redis-cli ping

# Server health endpoint
curl http://localhost:8080/health

# Check all services
docker ps

Log Locations

# Server logs
tail -f logs/tmi.log

# PostgreSQL logs
tail -f /var/log/postgresql/postgresql-*.log

# Redis logs
tail -f /var/log/redis/redis-server.log

# Docker logs
docker logs tmi-server
docker logs tmi-postgres
docker logs tmi-redis

Common Fix Commands

# Restart all services
make restart

# Reset database (development)
make db-reset

# Clear Redis cache
redis-cli FLUSHDB

# Rebuild containers
make containers-build

# Run migrations
./bin/migrate up

Related Documentation

Home

Getting Started

Deployment

Operation

Troubleshooting

Development

Integrations

Tools

API Reference

Reference

Clone this wiki locally