Application debug page guide
Application debug page guide
The debug page is a comprehensive diagnostic tool that monitors your application's health and identifies issues automatically. It analyzes your application's running environment and provides actionable recommendations when problems are detected.
What the debug page does
The debug page continuously monitors several aspects of your application:
Application Status: Tracks if your application instances are running properly
Build Process: Monitors whether your application builds successfully from your code
Health Checks: Verifies your application responds correctly to traffic
Resource Usage: Detects memory and performance issues
Configuration Problems: Identifies missing dependencies or configuration errors
How it works
Data collection
The debug system connects to your application environment and gathers information from:
Running application instances
Build logs and processes
Application deployments
Network routing configuration
Recent system events
Issue detection
The system automatically scans for common problems:
Build failures from missing dependencies or configuration errors
Application crashes from memory issues or code errors
Health check failures when your application doesn't respond properly
Resource problems like running out of memory
Initialization errors during application startup
Smart analysis
For each detected issue, the system:
Analyzes error logs to identify the root cause
Extracts specific error messages and stack traces
Categorizes issues by severity (critical, warning, info)
Generates actionable recommendations
Understanding the debug interface
Status overview
The top section shows your overall application health:
Green (All systems operational): No critical issues detected
Red (Critical issues detected): Problems requiring immediate attention
Gray (Unable to check status): Debug information couldn't be retrieved
Issues list
When problems are found, each issue card displays:
Issue Type Icon: 🔨 Build, 📦 Instance, ⚙️ Application, 🌐 Routing
Severity Badge: Critical, Warning, or Info
Clear Description: What's wrong in plain language
Action Steps: Specific steps to resolve the issue
Technical Details: Error codes, logs, and diagnostic information
Source: Which part of your application is affected
Common issues and how to fix them
Build problems
Build Failed
What it means: Your application couldn't be built from your source code
Common causes: Missing dependencies, syntax errors, configuration problems
Actions to take:
Check the build output in the expandable logs section
Look for specific error messages about missing files or dependencies
Fix any syntax errors in your code
Ensure all required dependencies are properly configured
Missing PHP Extensions
What it means: Your code requires PHP extensions that aren't enabled
Actions to take:
Go to Settings > PHP Extensions
Enable the missing extensions listed in the error
Redeploy your application
Vite Manifest Missing
What it means: Frontend assets weren't built properly
Actions to take:
Enable Node.js in Settings
Add "npm run build" to your build commands
Redeploy your application
Runtime problems
Application Crashing
What it means: Your application starts but then stops unexpectedly
Actions to take:
Review the crash logs in the debug details
Look for specific error types:
Database Connection: Check database service status and connection settings
Memory Exhausted: Increase memory limits in Settings > Resources
Missing Files: Ensure all required files are in your repository
Syntax Errors: Fix code syntax problems
Out of Memory (OOM)
What it means: Your application used more memory than allocated
Actions to take:
Go to Settings > Resources
Increase the memory allocation
Redeploy your application
Health Check Failing
What it means: Your application isn't responding properly to health checks
Common HTTP status codes:
500 (Internal Server Error): Application has errors - check error logs
404 (Not Found): Health check endpoint missing - verify configuration
503 (Service Unavailable): Application not ready - check if services are running
Actions to take:
Check application logs for specific errors
Verify your health check endpoint is working
Ensure database and other services are running
Initialization problems
Database Migrations Failed
What it means: Database setup or updates failed during deployment
Actions to take:
Check the migration logs in the debug details
Fix any database migration errors
Ensure database service is running and accessible
Application Initialization Failed
What it means: Setup tasks failed before your application could start
Actions to take:
Review initialization logs for specific errors
Check that all environment variables are properly set
Verify file permissions and dependencies
Exit codes and their meanings
When applications crash, you may see exit codes that help identify the cause:
Exit 137: Terminated by health check after repeated failures, or forcefully terminated due to memory limits
Exit 1: Application exited with an error
Exit 143: Gracefully terminated (normal during deployments)
Exit 0: Normal exit (but unexpected in this context)
Exit 255: Exit code out of range (invalid exit status)
Best practices for using the debug page
Regular monitoring
Check the debug page when your application isn't working as expected
Use the refresh button to get the latest status
Monitor after deployments to catch issues early
Reading error information
Start with the issue title and action steps
Expand log sections for detailed technical information
Focus on the most recent errors first
Look for patterns in repeated errors
Taking action
Follow the recommended actions in order of severity (critical first)
Make one change at a time and test
Use the logs to verify fixes are working
Redeploy when configuration changes are needed
When to contact support
Contact support if:
Issues persist after following all recommended actions
Error messages are unclear or not covered in this guide
The debug page shows "Unable to check status" repeatedly
You see infrastructure-related errors you can't resolve
Technical details
The debug system examines:
Instance Status: Running, pending, failed, or crashed application instances
Container States: Memory usage, restart counts, exit codes
Build Jobs: Success/failure status of recent builds
Event History: Recent warnings and errors from the platform
Log Analysis: Automatic extraction of error messages and stack traces
Error severity levels:
Critical: Issues preventing your application from working
Warning: Problems that may cause issues but don't stop functionality
Info: Informational notices about configuration or recommendations