Generated from docs/revenuepilot-troubleshooting.md.

RevenuePilot Troubleshooting

Check that the demo seed has been run:

php artisan crm:demo-seed

Then try:

Admin: admin@ovion.tech
Client: apex-client@revenuepilot.test
Admin password: Demo@12345
Client password: password

Pages Show Missing Table Errors

Run migrations:

php artisan migrate

Then clear cached views:

php artisan view:clear
php artisan view:cache

Installer Step 4 Retry Drops Tables

If installer Step 4 fails during migrations or required seeding, use Retry only for the configured installer database. The retry confirmation runs a guarded fresh reset: it is available only while the installer is unlocked, requires explicit confirmation, drops all tables in the configured database, clears setup state, and reruns migrations and seeders from the beginning.

After the installer is locked, the fresh reset is blocked. Use the authenticated reinstall/unlock flow only when you intentionally want to reopen installation.

Installer Step 5 Required Settings

Step 5 writes required runtime deployment values as part of the existing 8-step installer. Confirm APP_URL, keep CENTRAL_DOMAINS aligned with the app host for single-domain installs, leave TENANT_DOMAIN_SUFFIX blank unless you intentionally use tenant subdomains, and verify the scheduler, queue worker, and storage-link guidance before launch.

cPanel Migration Index Errors

The installer uses InnoDB and 191-character indexed string defaults for MySQL/MariaDB compatibility. If a shared host still reports index-length or table-exists errors, confirm the database uses MySQL/MariaDB with InnoDB support, then use the guarded Step 4 Retry only while installing so the configured installer database is wiped and migrations rerun cleanly.

Production Readiness Shows Warnings

Open CRM > System Health before release. The readiness center checks the scheduler, queue worker, failed jobs, migrations, writable storage, storage link, mail, AI provider activity, webhook verification, backup freshness, restore rehearsal, demo mode, installed lock state, Admin MFA policy, and unsafe environment flags.

Warnings mean the app can usually run but needs attention. Critical items should be fixed before public launch.

Demo Routes Are Not Visible

The public welcome/demo page is intentionally hidden by default. Enable demo_mode_enabled in Settings > General to expose /demo-preview. Table demo routes remain authenticated and require use tools plus demo/debug mode.

Provider Or Mail Tests Hide Raw Errors

Settings test endpoints redact tokens, API keys, secrets, credential-bearing URLs, and provider debug payloads. Check storage/logs/laravel.log and provider dashboards for full diagnostics, but never paste live secrets into support tickets.

Webhooks Return 401 Or 202 Without Processing

Public webhooks are throttled and validate shared secrets, signatures, or scoped tokens where configured. Missing or invalid signatures are rejected. Duplicate event ids or idempotency keys return success-style responses without reprocessing.

Rotate provider shared secrets from POST /settings/webhooks/{provider}/rotate-secret while signed in as an admin with Settings permission, then update the same value at the provider.

Backup Restore Rehearsal Fails

Use the Rehearse action on a backup before a destructive restore. Rehearsal verifies the archive exists, checksum matches, JSON manifest is readable, app version metadata is compatible, and expected record groups are present. A failed rehearsal does not overwrite live data.

Uploads Are Blocked

CRM and portal uploads run through a shared scanner for blocked extensions, PHP/executable signatures, MIME allowlists, randomized storage names, and an optional ClamAV-compatible hook when upload_scanner_enabled is enabled. Rename or re-export the file in an allowed format and try again.

Payment Links Are Not Charging Real Money

This release uses sandbox/config-ready payment gateways and local simulation. Demo seed creates sandbox records for Stripe, PayPal, Mollie, and Authorize.net. Configure real provider credentials, webhook secrets, queue workers, and scheduler checks only when the buyer is ready for production capture.

Mailbox Import Is Not Reading Real Email

Mailbox import defaults to simulation/configure-later mode for marketplace safety. To import real email, configure host, port, TLS/SSL, auth mode, username, credential/OAuth provider, and set the mailbox live import flag before running php artisan crm:sync-support-mailboxes. The importer dedupes by UID/message-id and records each import in the mailbox logs.

Documentation Screenshots

Seed the demo and run node scripts/capture-marketplace-screenshots.mjs to capture the canonical marketplace set into the root /screenshots folder. Documentation and package builds copy from that folder; documentation/assets/media/marketplace-proof is retained only for legacy assets.

Support Tickets Return 403

Run the role seed and confirm the signed-in admin has view support tickets, manage support tickets, and assign support tickets:

php artisan db:seed --class=RoleAndPermissionSeeder --force

Then sign out and back in before browser QA.

Portal Readiness Shows Warnings

Run the demo seed and the parity commands:

php artisan crm:demo-seed
php artisan crm:sync-support-mailboxes
php artisan crm:run-recurring-billing
php artisan crm:sync-payment-gateways
php artisan crm:retry-payment-events
php artisan crm:portal-readiness-check

The readiness output should show portal users, active gateways, active support mailboxes, active recurring expenses, portal delivery notes, and an empty warnings array. A zero due_recurring_expenses value is acceptable.