# Troubleshooting Guide

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

#### On this page

- Installation Issues
- Build Issues
- Payment Issues
- Common Errors
- Getting Support

## 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

© 2026 Titan Systems. All Rights Reserved.