Troubleshooting

Setup checker returns 404

This is the secure default. Add a temporary setup_token to config.php, set enable_install to true, and use the exact token in /install.php?token=.... Disable the flag and remove the token immediately after the check.

Admin remains locked

Confirm config.php exists and contains admin_username plus a non-example admin_password_hash. Browser-installed sites use the username and password chosen during setup. Older upgraded sites default to username admin unless changed in config.

Iframe compatibility

Some sites block framing with X-Frame-Options or Content-Security-Policy frame-ancestors. If /demo/ is blank, test another destination, ask the destination owner to allow framing, or link directly instead.

Email delivery

Start with mail_mode => log and inspect storage/mail.log through private hosting access, never a public URL. For production, use mail only when the host has working PHP mail, SPF/DKIM/DMARC are configured, and messages arrive in real inboxes. Check host limits and ensure from_email uses an authenticated sender domain.

Permissions

storage/ and uploads/ must be writable by PHP but not publicly readable. Permissions vary by host; do not use world-writable permissions unless the provider explicitly requires and isolates them.

MOD Manager requires HTTPS

Set base_url to the installation’s exact https:// URL and access Admin through HTTPS. Reverse proxies must pass the original HTTPS scheme correctly. Home Base marketplace connections are intentionally rejected over plain HTTP.

MOD verification key is not configured

Keep keys/mod-signing-public.pem from the official release. In Admin’s MOD Manager, use the action to install or refresh the Home Base public verification key. The file is public verification material, not the private signing key. Make sure keys/ is writable only when the refresh needs it.

Owned MOD has no install button

Home Base must have a published compatible release for that MOD and your entitlement must cover its version. Refresh entitlements, confirm the core/PHP requirements and dependencies, and check that the release is published rather than only the catalog product.

MOD is not compatible

Compare the MOD’s required core version, PHP version/extensions, dependencies, and conflicts with the installation. Install dependencies first. Do not edit mod.json or bypass signature checks; request a compatible signed release.

Google reCAPTCHA or payments fail

These optional integrations require PHP cURL, outbound HTTPS, valid provider credentials, correct return/webhook URLs, and a host that trusts current certificate authorities. Use Google, Stripe, and PayPal test modes before production. The in-house Pro Captcha mode does not require Google credentials.