Debug Commands

MikroORM CLI debugging and diagnostic commands for troubleshooting configuration issues, validating setup, and inspecting the CLI environment.

Capabilities

Debug Configuration

Comprehensive debugging command that validates and displays CLI configuration, dependencies, database connectivity, and entity discovery status.

/**
 * Debug CLI configuration command
 */
command: "debug"

// No additional options beyond global options

Usage Examples:

# Debug with default configuration
mikro-orm debug

# Debug with specific config file
mikro-orm debug --config ./orm.config.js

# Debug specific context
mikro-orm debug --context production

Debug Output Information

The debug command provides comprehensive system information:

System Information

• MikroORM version: Current MikroORM CLI version
• Node.js version: Runtime Node.js version
• TypeScript status: TypeScript availability and ts-node configuration
• Package.json status: Whether package.json exists in current directory

Configuration Validation

• Config file search: Lists all searched configuration paths
• Config file status: Whether configuration was found and loaded successfully
• Context validation: Confirms specified context name is valid
• Driver dependencies: Lists database driver dependencies and their versions

Database Connectivity

• Connection test: Tests database connection and reports status
• Connection details: Reports connection success or failure reason
• Driver validation: Confirms database driver is properly configured

Entity Discovery

• Entity configuration: Reports preferTs flag setting and implications
• Entity arrays: Shows configured entities and entitiesTs arrays
• Path validation: Validates entity file paths exist on filesystem
• Discovery warnings: Reports potential entity discovery issues

Error Diagnosis

The debug command helps diagnose common issues:

Configuration Issues

# Example output for missing config
mikro-orm debug
# Output: - configuration not found (Configuration file not found...)

Database Connection Problems

# Example output for connection failure
mikro-orm debug
# Output: - database connection failed (Connection refused)

Entity Discovery Problems

# Example output for missing entity files
mikro-orm debug
# Output: - ./src/entities/*.ts (not found)

Debug Implementation

The debug command performs these validation steps:

Path Checking

/**
 * Internal path validation method
 */
private static async checkPaths(
  paths: string[], 
  failedColor: 'red' | 'yellow', 
  baseDir?: string
): Promise<void>;

This method:

• Resolves relative paths to absolute paths
• Normalizes path separators
• Checks filesystem existence
• Reports status with color coding (green=found, red/yellow=not found)

Connection Testing

The debug command tests database connectivity by:

• Establishing database connection
• Running connection health check
• Reporting detailed connection status
• Closing connection cleanly

Global Options

The debug command supports:

• --config: Path to ORM configuration file(s)
• --contextName / --context: Configuration context name

Error Handling

Common Debug Scenarios

• Configuration not found: Provides searched paths and suggestions
• Invalid context: Reports available contexts if configuration loads
• Connection failures: Displays specific connection error messages
• Missing dependencies: Shows which database drivers are missing
• Path resolution: Reports which entity paths cannot be resolved

Output Formatting

Debug output uses color coding:

• Green: Successful validations and found items
• Yellow: Warnings and potential issues
• Red: Errors and missing required items
• Cyan: Highlighting important values

Troubleshooting Guide

Common Issues and Solutions

Configuration Not Found

# Issue: Configuration file not found
# Solution: Check config file paths or specify explicitly
mikro-orm debug --config ./custom-config.js

Database Connection Failed

# Issue: Cannot connect to database
# Check: Database server running, credentials correct, network accessible
# Verify: Connection string format and database existence

TypeScript Issues

# Issue: ts-node not working properly
# Check: TypeScript and ts-node installation
# Verify: tsconfig.json configuration

Entity Discovery Problems

# Issue: Entities not found
# Check: Entity file paths in configuration
# Verify: Files exist at specified locations
# Confirm: Entity exports are correct

Best Practices

Development Workflow

1. Start with debug: Run mikro-orm debug when setting up new projects
2. Verify configuration: Ensure all paths and settings are correct
3. Test connectivity: Confirm database connection before other operations
4. Check dependencies: Verify all required packages are installed

Production Deployment

1. Pre-deployment check: Run debug command in production environment
2. Environment variables: Verify database credentials and connection strings
3. File permissions: Ensure entity files are accessible
4. Network connectivity: Confirm database server accessibility

Configuration Validation

The debug command validates:

• Configuration file syntax and structure
• Database connection parameters
• Entity file accessibility
• Dependency availability
• TypeScript compilation setup