Troubleshooting
This section helps you diagnose and resolve common issues when working with Watt and Platformatic applications.
Common Issues and Solutions
Installation and Setup Issues
"Command not found: wattpm"
Problem: After installing wattpm
, the command is not recognized.
Solution:
# If installed globally, ensure npm global bin is in your PATH
npm list -g --depth=0
npm config get prefix
# If the prefix is not in your PATH, add it:
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
# Alternatively, install locally and use npx:
npm install wattpm
npx wattpm --help
Configuration File Not Found
Problem: Error: "No config file found" or "Cannot parse config file"
Solution:
-
Ensure you have a configuration file in the current directory:
watt.json
(recommended for Watt applications)
-
Check file format and syntax:
# Validate JSON syntax
cat watt.json | jq . -
Use the
--config
option to specify a custom path:wattpm start --config ./config/my-watt.json
Database Connection Issues
Database Connection Failed
Problem: "Connection refused" or "Authentication failed" errors.
Solution:
-
Check connection string format:
// PostgreSQL
'postgres://username:password@host:port/database'
// MySQL
'mysql://username:password@host:port/database'
// SQLite
'sqlite://./path/to/database.sqlite' -
Test database connectivity:
# PostgreSQL
psql "postgres://user:pass@host:port/db" -c "SELECT 1;"
# MySQL
mysql -h host -P port -u user -p database -e "SELECT 1;" -
Use environment variables for credentials:
{
"db": {
"connectionString": "{PLT_DATABASE_URL}"
}
}export PLT_DATABASE_URL="postgres://user:pass@localhost:5432/mydb"
Migrations Not Applied
Problem: "You have migrations to apply" error.
Solution:
# Apply pending migrations
wattpm db:migrations:apply
K```
### Application Discovery and Communication Issues
#### Application Not Found
**Problem:** "Application not found" or "Application with id 'X' is not started" errors.
**Solution:**
1. **Check running applications:**
```bash
wattpm ps
wattpm applications
-
Verify application configuration:
wattpm config
-
Check application health:
wattpm inject --path /health
wattpm logs application-name
Port Already in Use
Problem: "EADDRINUSE: address already in use" error.
Solution:
# Find process using the port
lsof -i :3042
# or
netstat -tulpn | grep 3042
# Kill the process (replace PID with actual process ID)
kill -9 PID
# Or change the port in configuration
Development and Hot Reload Issues
Changes Not Reflected
Problem: Code changes don't appear when running wattpm dev
.
Solution:
-
Check watch configuration:
{
"watch": {
"enabled": true,
"path": "./src",
"ignore": ["*.test.js", "node_modules"]
}
} -
Restart development server:
# Stop current process (Ctrl+C)
wattpm dev -
Check file permissions and symlinks:
ls -la ./src
TypeScript Issues
TypeScript Compilation Errors
Problem: "Cannot find module" or TypeScript compilation errors.
Solution:
# Compile TypeScript plugins
wattpm build
# Generate TypeScript types
wattpm db:types
# Check TypeScript configuration
cat tsconfig.json
Production Deployment Issues
Build Failures
Problem: Application fails to build for production.
Solution:
-
Check dependencies:
wattpm install --production
-
Compile all applications:
wattpm build
-
Check for missing environment variables:
wattpm env
Performance Issues
Problem: Slow response times or high memory usage in production.
Solution:
-
Enable metrics collection:
{
"metrics": {
"enabled": true,
"endpoint": "/metrics"
}
} -
Check logs for errors:
wattpm logs --level error
-
Monitor resource usage:
wattpm inject --path /metrics
Error Reference
Configuration Errors
Error Code | Description | Solution |
---|---|---|
PLT_CONFIG_NO_CONFIG_FILE_FOUND | Configuration file not found | Create a watt.json or use --config option |
PLT_CONFIG_CANNOT_PARSE_CONFIG_FILE | Invalid configuration file syntax | Validate JSON/YAML syntax |
PLT_CONFIG_VALIDATION_ERRORS | Configuration doesn't match schema | Check configuration against schema |
PLT_CONFIG_ENV_VAR_MISSING | Environment variable not set | Set required environment variables |
Database Errors
Error Code | Description | Solution |
---|---|---|
PLT_SQL_MAPPER_CONNECTION_STRING_REQUIRED | Missing database connection | Add connectionString to config |
PLT_DB_MIGRATIONS_TO_APPLY_ERROR | Pending migrations | Run wattpm db:migrations:apply |
PLT_DB_UNKNOWN_DATABASE_ERROR | Unsupported database | Use PostgreSQL, MySQL, MariaDB, or SQLite |
Runtime Errors
Error Code | Description | Solution |
---|---|---|
PLT_RUNTIME_EADDR_IN_USE | Port already in use | Change port or kill existing process |
PLT_RUNTIME_APPLICATION_NOT_FOUND | Application not found | Check application ID and configuration |
PLT_RUNTIME_APPLICATION_NOT_STARTED | Application not running | Start application with wattpm start |
For a complete list of error codes, see the Error Reference.
Debugging Techniques
Enable Debug Logging
# Enable debug logs
DEBUG=platformatic:* wattpm dev
# Or set log level in configuration
{
"server": {
"logger": {
"level": "debug"
}
}
}
Use the Inspector
# Start with Node.js inspector
wattpm start --inspect
# Then connect Chrome DevTools or VS Code
Check Application Health
# Test individual application endpoints
wattpm inject --path /health
wattpm inject --path /metrics
wattpm inject --path /documentation/json
# View application configuration
wattpm config application-name
Monitor Logs in Real-time
# Stream all logs
wattpm logs
# Stream logs from specific application
wattpm logs my-app api-application
# Filter by log level
wattpm logs --level error
Observability Architecture Diagrams
Understanding how observability works in Watt applications is crucial for effective debugging. Logs, telemetry tracing, and metrics have three completely different implementations and data flows.
Logging Flow
Watt uses Pino for high-performance logging with centralized log streaming through the Runtime API:
graph TD
A[Watt Application] --> B[Application Worker 1]
A --> C[Application Worker 2]
A --> D[Application Worker N]
B --> E[Pino Logger]
C --> F[Pino Logger]
D --> G[Pino Logger]
E --> H[Runtime Process]
F --> H
G --> H
H --> I[Log Files<br/>pino-roll]
H --> J[Management API<br/>getRuntimeLiveLogsStream]
J --> K[wattpm logs<br/>command]
L[External Log Aggregator<br/>ELK/Fluentd] --> I
style A fill:#e1f5fe
style H fill:#f3e5f5
style K fill:#e8f5e8
style L fill:#fff3e0
Key Points:
- Each worker application uses its own Pino logger instance
- All logs flow through the main Runtime process
- Runtime API provides live log streaming for CLI commands
- Logs are persisted to rotating files using pino-roll
- External systems can consume log files directly
Telemetry Tracing Flow
Watt implements distributed tracing using OpenTelemetry with automatic span propagation across applications:
graph TD
A[Incoming Request] --> B[Watt Application]
B --> C[Fastify onRequest Hook]
C --> D[OpenTelemetry Plugin<br/>startHTTPSpan]
D --> E[Application Worker 1]
D --> F[Application Worker 2]
E --> G[Inter-application Call<br/>undici interceptor]
F --> H[Database Query<br/>auto-instrumentation]
G --> I[Trace Context<br/>Propagation]
H --> I
I --> J[OTLP Exporter]
I --> K[Jaeger Exporter]
I --> L[Zipkin Exporter]
J --> M[OpenTelemetry Collector]
K --> N[Jaeger Backend]
L --> O[Zipkin Backend]
M --> P[Observability Platform<br/>Jaeger/Grafana/etc]
N --> P
O --> P
style A fill:#e1f5fe
style D fill:#f3e5f5
style I fill:#e8f5e8
style P fill:#fff3e0
Key Points:
- Each application has its own OpenTelemetry plugin instance
- Traces automatically span across application boundaries
- Context propagation happens via HTTP headers
- Multiple exporter types supported (OTLP, Jaeger, Zipkin)
- Custom spans can be created using
app.openTelemetry.startSpan()
Metrics Collection Flow
Watt exposes Prometheus-compatible metrics through a dedicated metrics server:
graph TD
A[Watt Application] --> B[Application Worker 1]
A --> C[Application Worker 2]
A --> D[Application Worker N]
B --> E[Fastify Metrics<br/>@fastify/metrics]
C --> F[Custom Metrics<br/>app.metrics.counter]
D --> G[System Metrics<br/>Node.js metrics]
E --> H[Runtime Process<br/>Metrics Aggregation]
F --> H
G --> H
H --> I[Prometheus Server<br/>:9090/metrics]
H --> J[Management API<br/>getRuntimeMetrics]
I --> K[Prometheus Scraper]
J --> L[wattpm metrics<br/>command]
K --> M[Prometheus Database]
M --> N[Grafana Dashboard]
M --> O[Alertmanager]
style A fill:#e1f5fe
style H fill:#f3e5f5
style I fill:#e8f5e8
style M fill:#fff3e0
Key Points:
- Each worker collects its own metrics (HTTP, custom, system)
- Runtime process aggregates metrics from all workers
- Dedicated Prometheus server runs on separate port (default 9090)
- Metrics available in both text and JSON formats
- Built-in health check endpoints (/ready, /status)
Observability Integration Patterns
For production deployments, these three systems work together:
graph LR
A[Watt Application] --> B[Logs]
A --> C[Traces]
A --> D[Metrics]
B --> E[ELK Stack]
C --> F[Jaeger/Tempo]
D --> G[Prometheus]
E --> H[Unified Dashboard<br/>Grafana]
F --> H
G --> H
H --> I[Alerting<br/>PagerDuty/Slack]
H --> J[APM Analysis<br/>Error Correlation]
style A fill:#e1f5fe
style H fill:#f3e5f5
style I fill:#ffebee
style J fill:#e8f5e8
Getting Additional Help
Community Resources
- Discord: Join our Discord server for real-time help
- GitHub Issues: Report bugs at github.com/platformatic/platformatic
- Documentation: Search this documentation for specific topics
Diagnostic Information
When asking for help, include this information:
# System information
node --version
npm --version
wattpm version
# Configuration (remove sensitive data)
cat watt.json
# Error logs
wattpm logs --level error > error.log
# Application status
wattpm ps
wattpm applications
Creating Minimal Reproductions
-
Create a minimal example:
wattpm create debug-app --skip-dependencies
cd debug-app
# Add only the problematic configuration -
Test the issue:
wattpm dev
# Document the steps to reproduce -
Share the reproduction with the community or support team.