Troubleshooting Guide

Solutions to common issues and errors you may encounter when using Appy.

Installation Issues

Problem: Requirements Check Fails

Symptoms: Red X marks appear on the requirements check page during installation.

Solutions:

• PHP Version: Contact your hosting provider to upgrade to PHP 8.2 or higher
• Missing Extensions: Ask your host to enable required PHP extensions
• Shared Hosting: Most modern shared hosts support PHP 8.2. Consider upgrading your hosting plan

Problem: Permission Errors

Symptoms: Folders show as not writable during installation.

Solutions:

1. Using FTP or your hosting file manager, set these folders to 755 permissions:
   • storage/
   • bootstrap/cache/
   • public/storage/
2. If 755 doesn't work, try 775 or 777 (less secure but may be necessary on some hosts)

Problem: Database Connection Error

Symptoms: "Could not connect to database" error during database setup.

Solutions:

• Verify database credentials are correct
• Ensure database exists (create it via cPanel/Plesk if needed)
• Check if database host is localhost or an IP address (ask your host)
• For SQLite: Ensure storage/database/ folder has write permissions

Problem: Blank Page After Installation

Symptoms: After completing installation, site shows a blank white page.

Solutions:

1. Check if .env file exists in your root directory
2. Clear browser cache and try again
3. Run: php artisan config:clear and php artisan cache:clear
4. Check error logs in storage/logs/ for specific errors

Build Issues

Problem: Build Stuck in "Pending" Status

Symptoms: Build stays in pending status for more than 10 minutes.

Solutions:

• Check if any builders are active in Admin > Builders
• Verify cron jobs are running: Admin > Cron Jobs
• Ensure at least one builder has status "active" and available queue slots
• Wait up to 15 minutes - high traffic may cause delays

Problem: Build Fails with Error

Symptoms: Build shows "failed" status.

Solutions:

1. Click View Logs to see error details
2. Common causes:
   • Invalid package name: Must be lowercase with dots (e.g., com.example.app)
   • Missing Firebase config: Upload google-services.json if using notifications
   • Keystore password incorrect: Verify keystore passwords for release builds
   • Builder timeout: Try again - may be temporary builder issue

Problem: Cannot Download Build

Symptoms: Download button doesn't work or shows 404 error.

Solutions:

• Check if build has expired (builds expire after 30 days by default)
• Trigger a new build
• Ensure storage/app/builds/ directory exists and has proper permissions

Problem: QR Code Not Working

Symptoms: Scanning QR code doesn't download the app.

Solutions:

• Ensure your device is on the internet
• Check if build link is accessible by opening it in a browser
• For Android: Enable "Install from unknown sources" in device settings
• Use the direct download button instead

Payment Issues

Problem: Payment Gateway Not Working

Symptoms: Users cannot complete payments or get errors during checkout.

Solutions:

• Verify payment gateway credentials in Admin > Plugins
• Check if gateway is in test mode vs. live mode
• Ensure webhook URLs are configured correctly
• Check gateway's dashboard for failed payment details

Problem: Subscription Not Activated After Payment

Symptoms: User paid but still shows free plan.

Solutions:

1. Check Admin > Transactions for payment status
2. Verify webhook is configured and receiving events
3. Manually activate subscription from Admin > Subscriptions
4. Check payment gateway webhook logs for errors

Problem: Cannot Cancel Subscription

Symptoms: Cancellation button doesn't work.

Solutions:

• Admin can manually cancel from Admin > Subscriptions
• User can cancel directly in payment gateway (Stripe, PayPal)
• Check browser console for JavaScript errors

Common Errors

Error: "403 Forbidden" or "API Access Denied"

Cause: User's plan doesn't include API access.

Solution:

• Upgrade to a plan with can_use_api feature enabled
• Admin can enable feature in Admin > Plans

Error: "Insufficient Build Credits"

Cause: User has used all monthly build credits.

Solution:

• Wait for monthly credit reset
• Upgrade to a plan with more credits
• Admin can manually add credits from Admin > Users

Error: "Email Sending Failed"

Cause: SMTP not configured or credentials incorrect.

Solution:

1. Verify SMTP settings in Admin > Settings > Email Settings
2. Send test email to verify configuration
3. Check if port 587 or 465 is blocked by your host
4. For Gmail: Use App Password instead of regular password

Error: "500 Internal Server Error"

Cause: Various server-side issues.

Solution:

1. Check storage/logs/laravel.log for specific error
2. Run php artisan config:clear
3. Ensure all required PHP extensions are enabled
4. Check file permissions on storage/ and bootstrap/cache/

Error: "Keystore Not Found" or "Invalid Keystore"

Cause: Keystore file missing or corrupted.

Solution:

• Re-upload keystore in Signing Keys tab
• Generate new keystore if original is lost
• Verify keystore passwords are correct
• Ensure keystore file is valid .jks or .keystore format

Getting Support

If you encounter issues not covered in this guide:

Before Contacting Support

1. Check the error logs in storage/logs/
2. Try clearing cache: php artisan config:clear && php artisan cache:clear
3. Search the documentation for your specific issue
4. Check if your software is up to date

Contact Support

Visit https://support.titansystems.ph to:

• Submit a support ticket
• Live chat with our team
• Browse the knowledge base

Information to Include

When contacting support, please provide:

• Appy version number
• PHP version and hosting environment
• Detailed description of the problem
• Steps to reproduce the issue
• Relevant error messages from logs
• Screenshots if applicable