Appendix E: Troubleshooting Guide

Common Issues and Solutions

Installation and Setup Issues

Issue: CLI Installation Fails

Symptoms:

$ dart pub global activate hypermodern_cli
Error: Could not resolve package hypermodern_cli

Solutions:

1. Check Dart SDK version:

dart --version
# Ensure you have Dart 3.0.0 or later

2. Update pub cache:

dart pub cache repair
dart pub global activate hypermodern_cli

3. Install from source:

git clone https://github.com/hypermodern/hypermodern_cli.git
cd hypermodern_cli
dart pub global activate --source path .

Issue: Command Not Found After Installation

Symptoms:

$ hypermodern --version
command not found: hypermodern

Solutions:

1. Add pub global bin to PATH:

# Add to ~/.bashrc or ~/.zshrc
export PATH="$PATH":"$HOME/.pub-cache/bin"

2. Verify installation:

dart pub global list
# Should show hypermodern_cli in the list

3. Use full path temporarily:

~/.pub-cache/bin/hypermodern --version

Code Generation Issues

Issue: Schema Validation Errors

Symptoms:

$ hypermodern generate
Error: Schema validation failed
- Invalid type reference '@unknown_model' in field 'user.profile'

Solutions:

1. Check model references:

{
  "models": {
    "user": {
      "profile": "@user_profile"  // Ensure user_profile exists
    },
    "user_profile": {  // Define the referenced model
      "bio": "string"
    }
  }
}

2. Validate schema syntax:

hypermodern schema validate schemas/

3. Check for circular references:

// Avoid this:
{
  "models": {
    "user": {
      "posts": ["@post"]
    },
    "post": {
      "author": "@user"  // This creates a circular reference
    }
  }
}

// Use this instead:
{
  "models": {
    "user": {
      "id": "int64",
      "posts": ["@post"]
    },
    "post": {
      "author_id": "int64"  // Reference by ID
    }
  }
}

Issue: Generated Code Compilation Errors

Symptoms:

$ dart analyze
error: The method 'fromJson' isn't defined for the class 'User'

Solutions:

1. Regenerate code:

hypermodern generate --clean

2. Check schema field types:

{
  "models": {
    "user": {
      "id": "int64",        // Use int64, not int
      "name": "string",     // Use string, not String
      "active": "bool"      // Use bool, not boolean
    }
  }
}

3. Verify imports in generated code:

// Check that generated files have proper imports
import 'dart:convert';
import 'dart:typed_data';

Server Issues

Issue: Server Won't Start

Symptoms:

$ hypermodern serve
Error: Failed to bind to port 8080

Solutions:

1. Check port availability:

# Check if port is in use
lsof -i :8080
netstat -an | grep 8080

2. Use different ports:

hypermodern serve --http-port 3000 --ws-port 3001 --tcp-port 3002

3. Check permissions:

# On Linux/macOS, ports < 1024 require root
sudo hypermodern serve --http-port 80
# Or use ports > 1024
hypermodern serve --http-port 8080

Issue: Database Connection Errors

Symptoms:

Error: Failed to connect to database
Connection refused: postgresql://localhost:5432/myapp

Solutions:

1. Verify database is running:

# PostgreSQL
pg_isready -h localhost -p 5432

# Check service status
systemctl status postgresql
brew services list | grep postgresql

2. Check connection string:

# Test connection manually
psql postgresql://username:password@localhost:5432/database_name

3. Update configuration:

# hypermodern.yaml
database:
  url: "postgresql://user:pass@localhost:5432/myapp"
  # Or use environment variable
  url: "${DATABASE_URL}"

4. Create database if it doesn't exist:

createdb myapp

Issue: Hot Reload Not Working

Symptoms:

• File changes don't trigger server restart
• Generated code is not updated

Solutions:

1. Check file watching:

# Start with explicit watch
hypermodern serve --watch

2. Verify file patterns:

# hypermodern.yaml
server:
  watch_patterns:
    - "schemas/**/*.json"
    - "lib/**/*.dart"
    - "config/**/*.yaml"

3. Check file permissions:

# Ensure files are readable
chmod -R 644 schemas/

4. Restart with clean generation:

hypermodern generate --clean
hypermodern serve

Client Issues

Issue: Connection Refused

Symptoms:

Exception: Connection refused: ws://localhost:8082

Solutions:

1. Verify server is running:

# Check if server is listening on the port
netstat -an | grep 8082

2. Check protocol and port:

// Ensure correct protocol and port
final client = HypermodernClient('ws://localhost:8082');  // WebSocket
// or
final client = HypermodernClient('http://localhost:8080'); // HTTP

3. Test with curl:

# Test HTTP endpoint
curl http://localhost:8080/health

# Test WebSocket (using websocat)
websocat ws://localhost:8082

Issue: Authentication Errors

Symptoms:

UnauthorizedException: Invalid token

Solutions:

1. Check token format:

// Ensure token is properly formatted
client.setAuthToken('Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...');
// or
client.setAuthToken('eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...');

2. Verify token expiration:

// Check if token is expired
final jwt = JWT.verify(token, SecretKey('your-secret'));
print('Token expires at: ${DateTime.fromMillisecondsSinceEpoch(jwt.payload['exp'] * 1000)}');

3. Check server configuration:

// Ensure JWT secret matches
final jwtService = JWTService(
  secretKey: 'your-secret-key',  // Must match client
  issuer: 'your-app',
);

Issue: Request Timeout

Symptoms:

TimeoutException: Request timed out after 30 seconds

Solutions:

1. Increase timeout:

final response = await client.request<User>(
  'get_user',
  request,
  timeout: Duration(minutes: 2),
);

2. Check server performance:

# Monitor server logs
hypermodern serve --verbose

3. Optimize database queries:

// Add database indexes
CREATE INDEX idx_users_email ON users(email);

// Use connection pooling
final pool = ConnectionPool(
  maxConnections: 20,
  connectionTimeout: Duration(seconds: 10),
);

Performance Issues

Issue: Slow Response Times

Symptoms:

• API responses taking > 1 second
• High CPU usage
• Memory leaks

Solutions:

1. Enable performance monitoring:

server.middleware.add(PerformanceMiddleware());

2. Check database query performance:

-- Enable query logging in PostgreSQL
ALTER SYSTEM SET log_statement = 'all';
ALTER SYSTEM SET log_min_duration_statement = 1000; -- Log queries > 1s

3. Use connection pooling:

final pool = ConnectionPool(
  minConnections: 5,
  maxConnections: 20,
  connectionTimeout: Duration(seconds: 10),
);

4. Enable caching:

server.middleware.add(CacheMiddleware(
  defaultTtl: Duration(minutes: 5),
));

Issue: Memory Leaks

Symptoms:

• Memory usage continuously increasing
• Server crashes with out-of-memory errors

Solutions:

1. Monitor memory usage:

Timer.periodic(Duration(minutes: 1), (_) {
  final rss = ProcessInfo.currentRss;
  print('Memory usage: ${rss ~/ (1024 * 1024)}MB');
});

2. Check for unclosed streams:

// Always close streams
final subscription = stream.listen(handler);
// Later...
await subscription.cancel();

3. Use weak references for caches:

final cache = <String, WeakReference<CachedData>>{};

4. Profile memory usage:

dart --observe lib/main.dart
# Then use Dart DevTools to analyze memory

Module Issues

Issue: Module Installation Fails

Symptoms:

$ hypermodern module install hypermodern_auth
Error: Module not found in registry

Solutions:

1. Check module name:

# Search for available modules
hypermodern module search auth

2. Install from local path:

hypermodern module install ./path/to/module

3. Check registry configuration:

# hypermodern.yaml
modules:
  registry_url: "https://registry.hypermodern.dev"

Issue: Module Dependency Conflicts

Symptoms:

Error: Dependency conflict
Module A requires hypermodern_auth ^1.0.0
Module B requires hypermodern_auth ^2.0.0

Solutions:

1. Update modules:

hypermodern module update

2. Check compatibility:

hypermodern module list --outdated

3. Use specific versions:

hypermodern module install hypermodern_auth@1.5.0

Deployment Issues

Issue: Docker Build Fails

Symptoms:

$ docker build -t myapp .
Error: dart: command not found

Solutions:

1. Use correct base image:

FROM dart:3.2-sdk AS build
# Not FROM ubuntu:latest

2. Multi-stage build:

# Build stage
FROM dart:3.2-sdk AS build
WORKDIR /app
COPY pubspec.yaml pubspec.lock ./
RUN dart pub get
COPY . .
RUN dart compile exe lib/main.dart -o server

# Runtime stage
FROM debian:bookworm-slim AS runtime
RUN apt-get update && apt-get install -y ca-certificates
COPY --from=build /app/server /app/server
EXPOSE 8080 8082 8081
CMD ["/app/server"]

Issue: Kubernetes Deployment Fails

Symptoms:

Pod status: CrashLoopBackOff
Error: Failed to bind to 0.0.0.0:8080

Solutions:

1. Check resource limits:

resources:
  requests:
    memory: "256Mi"
    cpu: "250m"
  limits:
    memory: "512Mi"
    cpu: "500m"

2. Verify environment variables:

env:
- name: DATABASE_URL
  valueFrom:
    secretKeyRef:
      name: app-secrets
      key: database-url

3. Check health probes:

livenessProbe:
  httpGet:
    path: /health
    port: 8080
  initialDelaySeconds: 30
  periodSeconds: 10
readinessProbe:
  httpGet:
    path: /ready
    port: 8080
  initialDelaySeconds: 5
  periodSeconds: 5

Debugging Techniques

Enable Debug Logging

// Server-side
Logger.instance.setLevel(LogLevel.debug);

// Client-side
final client = HypermodernClient(
  'ws://localhost:8082',
  config: ClientConfig(
    logLevel: LogLevel.debug,
  ),
);

Use Request Tracing

server.middleware.add(TracingMiddleware());

// Each request gets a trace ID
final traceId = request.context['trace_id'];
logger.debug('Processing request', extra: {'trace_id': traceId});

Monitor Metrics

server.middleware.add(MetricsMiddleware());

// View metrics
final metrics = server.getMetrics();
print('Request count: ${metrics.requestCount}');
print('Average response time: ${metrics.averageResponseTime}ms');

Database Query Logging

final database = Database(pool, config: DatabaseConfig(
  logQueries: true,
  logSlowQueries: Duration(milliseconds: 100),
));

Performance Profiling

CPU Profiling

# Start server with profiling
dart --observe lib/main.dart

# Open Dart DevTools
dart devtools

Memory Profiling

import 'dart:developer';

void trackMemoryUsage() {
  Timeline.startSync('memory_check');
  final rss = ProcessInfo.currentRss;
  Timeline.finishSync();
  
  print('Memory usage: ${rss ~/ (1024 * 1024)}MB');
}

Network Profiling

# Monitor network traffic
tcpdump -i lo0 port 8080

# Monitor WebSocket connections
websocat -v ws://localhost:8082

Common Error Messages

Schema Errors

Error	Cause	Solution
Invalid type reference '@model'	Referenced model doesn't exist	Define the model or fix the reference
Circular reference detected	Models reference each other	Use ID references instead of object references
Invalid field name 'class'	Using reserved keyword	Rename field to non-reserved name

Runtime Errors

Error	Cause	Solution
Connection refused	Server not running or wrong port	Check server status and port configuration
Invalid token	JWT token expired or malformed	Refresh token or check token format
Database connection failed	Database not accessible	Check database status and connection string

Build Errors

Error	Cause	Solution
dart: command not found	Dart SDK not installed	Install Dart SDK
Package not found	Missing dependency	Run dart pub get
Compilation failed	Syntax errors in generated code	Regenerate code with hypermodern generate --clean

Getting Help

Community Resources

• GitHub Issues: Report bugs and feature requests
• Discord Server: Real-time community support
• Stack Overflow: Tag questions with hypermodern
• Documentation: Official docs at docs.hypermodern.dev

Diagnostic Information

When reporting issues, include:

# System information
hypermodern doctor

# Version information
hypermodern --version
dart --version

# Configuration
hypermodern config list

# Logs
hypermodern serve --verbose > server.log 2>&1

Creating Minimal Reproductions

1. Create a minimal project that reproduces the issue
2. Include schema files and configuration
3. Provide step-by-step instructions
4. Include error messages and logs
5. Specify environment details (OS, Dart version, etc.)

This troubleshooting guide covers the most common issues you might encounter when working with Hypermodern. For issues not covered here, consult the community resources or create a detailed bug report.