0
# Debug Commands
1

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

4
## Capabilities
5

6
### Debug Configuration
7

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

10
```typescript { .api }
11
/**
12
 * Debug CLI configuration command
13
 */
14
command: "debug"
15

16
// No additional options beyond global options
17
```
18

19
**Usage Examples:**
20

21
```bash
22
# Debug with default configuration
23
mikro-orm debug
24

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

28
# Debug specific context
29
mikro-orm debug --context production
30
```
31

32
## Debug Output Information
33

34
The debug command provides comprehensive system information:
35

36
### System Information
37

38
- **MikroORM version**: Current MikroORM CLI version
39
- **Node.js version**: Runtime Node.js version
40
- **TypeScript status**: TypeScript availability and ts-node configuration
41
- **Package.json status**: Whether package.json exists in current directory
42

43
### Configuration Validation
44

45
- **Config file search**: Lists all searched configuration paths
46
- **Config file status**: Whether configuration was found and loaded successfully
47
- **Context validation**: Confirms specified context name is valid
48
- **Driver dependencies**: Lists database driver dependencies and their versions
49

50
### Database Connectivity
51

52
- **Connection test**: Tests database connection and reports status
53
- **Connection details**: Reports connection success or failure reason
54
- **Driver validation**: Confirms database driver is properly configured
55

56
### Entity Discovery
57

58
- **Entity configuration**: Reports `preferTs` flag setting and implications
59
- **Entity arrays**: Shows configured `entities` and `entitiesTs` arrays
60
- **Path validation**: Validates entity file paths exist on filesystem
61
- **Discovery warnings**: Reports potential entity discovery issues
62

63
## Error Diagnosis
64

65
The debug command helps diagnose common issues:
66

67
### Configuration Issues
68

69
```bash
70
# Example output for missing config
71
mikro-orm debug
72
# Output: - configuration not found (Configuration file not found...)
73
```
74

75
### Database Connection Problems
76

77
```bash
78
# Example output for connection failure
79
mikro-orm debug
80
# Output: - database connection failed (Connection refused)
81
```
82

83
### Entity Discovery Problems
84

85
```bash
86
# Example output for missing entity files
87
mikro-orm debug
88
# Output: - ./src/entities/*.ts (not found)
89
```
90

91
## Debug Implementation
92

93
The debug command performs these validation steps:
94

95
### Path Checking
96

97
```typescript { .api }
98
/**
99
 * Internal path validation method
100
 */
101
private static async checkPaths(
102
  paths: string[], 
103
  failedColor: 'red' | 'yellow', 
104
  baseDir?: string
105
): Promise<void>;
106
```
107

108
This method:
109
- Resolves relative paths to absolute paths
110
- Normalizes path separators
111
- Checks filesystem existence
112
- Reports status with color coding (green=found, red/yellow=not found)
113

114
### Connection Testing
115

116
The debug command tests database connectivity by:
117
- Establishing database connection
118
- Running connection health check
119
- Reporting detailed connection status
120
- Closing connection cleanly
121

122
## Global Options
123

124
The debug command supports:
125
- `--config`: Path to ORM configuration file(s)
126
- `--contextName` / `--context`: Configuration context name
127

128
## Error Handling
129

130
### Common Debug Scenarios
131

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

138
### Output Formatting
139

140
Debug output uses color coding:
141
- **Green**: Successful validations and found items
142
- **Yellow**: Warnings and potential issues
143
- **Red**: Errors and missing required items
144
- **Cyan**: Highlighting important values
145

146
## Troubleshooting Guide
147

148
### Common Issues and Solutions
149

150
#### Configuration Not Found
151
```bash
152
# Issue: Configuration file not found
153
# Solution: Check config file paths or specify explicitly
154
mikro-orm debug --config ./custom-config.js
155
```
156

157
#### Database Connection Failed
158
```bash
159
# Issue: Cannot connect to database
160
# Check: Database server running, credentials correct, network accessible
161
# Verify: Connection string format and database existence
162
```
163

164
#### TypeScript Issues
165
```bash
166
# Issue: ts-node not working properly
167
# Check: TypeScript and ts-node installation
168
# Verify: tsconfig.json configuration
169
```
170

171
#### Entity Discovery Problems
172
```bash
173
# Issue: Entities not found
174
# Check: Entity file paths in configuration
175
# Verify: Files exist at specified locations
176
# Confirm: Entity exports are correct
177
```
178

179
## Best Practices
180

181
### Development Workflow
182

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

188
### Production Deployment
189

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

195
### Configuration Validation
196

197
The debug command validates:
198
- Configuration file syntax and structure
199
- Database connection parameters
200
- Entity file accessibility
201
- Dependency availability
202
- TypeScript compilation setup