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:

1. Check the build output in the expandable logs section
2. Look for specific error messages about missing files or dependencies
3. Fix any syntax errors in your code
4. 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:

1. Go to Settings > PHP Extensions
2. Enable the missing extensions listed in the error
3. Redeploy your application

Vite Manifest Missing

What it means: Frontend assets weren't built properly

Actions to take:

1. Enable Node.js in Settings
2. Add "npm run build" to your build commands
3. Redeploy your application

Runtime problems

Application Crashing

What it means: Your application starts but then stops unexpectedly

Actions to take:

1. Review the crash logs in the debug details

2. 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:

1. Go to Settings > Resources
2. Increase the memory allocation
3. 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:

1. Check application logs for specific errors
2. Verify your health check endpoint is working
3. 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:

1. Check the migration logs in the debug details
2. Fix any database migration errors
3. Ensure database service is running and accessible

Application Initialization Failed

What it means: Setup tasks failed before your application could start

Actions to take:

1. Review initialization logs for specific errors
2. Check that all environment variables are properly set
3. 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