Setup issues, causes and solutions
Find the failing stage, read its exact message, correct the prerequisite and use the existing recheck/continue action. Keep the original workspace and private journals so the system can verify completed steps.
The table distinguishes source-enforced failure cases from previously recorded fixes. A code/fixture-verified recovery is not proof that it has passed on every hosting provider. No live hosting, database, SMTP or gateway recovery was exercised while updating this guide.
Workspace preparation and access
| Symptom | Likely cause | Solution and verification |
|---|
| Customer or plan selector is empty | No eligible active customer, customer already linked, or no published eligible plan. | Create an Active customer and publish an eligible plan. For an existing workspace, continue its Setup instead. Confirm both selectors populate. |
| Slug rejected / duplicate workspace | Invalid/reserved slug, another workspace using the slug, or the same customer already assigned. | Use a letter-first slug such as asha-retail, with lowercase letters/numbers and separated hyphens. Avoid reserved names. Open the existing customer workspace when present. |
| Plan changed / stale form / state changed | Published version or record revision changed after the form opened. | Refresh the record, review the latest plan/setup state and reselect. Do not repeatedly submit the old form. Confirm the updated record saves once. |
| Waiting for publication after initialization | No allowed current agreement/provider billing, suspension, changed binding, or stale background evidence. | Check Subscription requested/applied access, agreement dates in platform timezone, verified billing receipts, suspension and cron/queue health. Allow the same worker to publish after the gate passes. |
| Open POS absent while status says Planned | Management status is not runtime readiness. | Check Setup completion, publication and applied access. A planned record can remain the management status after setup; Open POS depends on actual readiness. |
| Billing handoff cannot link a manual workspace | Original POS owner email differs from active customer, conflicting/unverified subscriber account, or incomplete/suspended workspace. | Review customer and original owner identity, unique subscriber link and current readiness. Use normal subscriber recovery where applicable. Confirm Renew / Manage billing reaches the correct account; never merge unrelated accounts to bypass the check. |
Subscriber domain, HTTPS and identity
| Symptom | Cause | Solution and verification |
|---|
| DNS Not verified | Subscriber addresses do not match the public platform host addresses, propagation pending, or inconsistent IPv4/IPv6. | Correct A/AAAA records for the exact hostname. Check all returned addresses, then rerun Verify domain. The check requires verified public addresses belonging to the application host. |
| HTTPS Not verified | Certificate missing/expired/wrong hostname, redirect, or incorrect origin. | Issue a trusted exact-host certificate and correct the virtual host. Remove redirects to another hostname; review proxy/CDN mapping with the operator. Rerun Verify domain without disabling certificate validation. |
| HTTPS works but Hyper-POS identity fails | Wrong document root, source core missing the optional shared routing hook, wrong/stale plugin, or unregistered platform/source roots. | Use the exact shared public root; deploy the compatible core including public/index.php and matching add-on. Open Super Admin so the configured shared bridge can register the verified roots. Confirm the three checks pass. |
| Workspace opens installer, source store or another workspace | Incorrect routing/configuration rather than readiness. | Stop customer use; check exact hostname, document root, compatible core/plugin and private shared routing registration. Pending workspaces must show the waiting page. Verify tenant identity before login. |
Database approval
| Symptom | Cause | Solution and verification |
|---|
| Access denied / connection failed | Wrong host/port/password, missing cPanel prefix, user not assigned, or unreachable database. | Copy the full database/user names from cPanel, verify assignment and provider connection values, then use Test and approve database. Do not send credentials to support. |
| Host rejected before connecting | Host not in the configured shared database allowlist. | Use localhost/127.0.0.1 when correct; otherwise ask the operator to approve the actual provider host through deployment configuration. A different host is not accepted merely because it connects from another client. |
| Database is not empty | Tables already exist, or the source/platform/another tenant database was selected. | Select a newly created empty subscriber database. Do not delete business tables to force approval. After partial activation, inspect/resume that activation rather than trying to approve its now-initialized database again. |
| Grants rejected | Global or other-database grants, roles, grant options or unknown grant patterns. | Use a dedicated user with only the required grants on this exact database. Ask the provider to remove broad privileges/roles. Repeat the read-only approval check. |
| Approved binding changed / credential journal unavailable | Workspace/runtime identity or saved encrypted profile changed; storage/key/read permissions no longer match. | Restore the correct configured binding and private storage/key through operator review. Re-enter credentials only through the supported approval path when appropriate; never copy encrypted profiles between tenants. |
Cron, queued setup and worker progress
| Symptom | Cause | Solution and verification |
|---|
| Queued with no recent update | Missing/wrong cron, incompatible CLI PHP, child-process restriction, or worker failure. | Copy the exact current panel command into one every-minute cPanel cron. Check cron output and hosting restrictions privately, then refresh scheduler and database queue timestamps. |
| Could not open input file: artisan on separate platform | Copied a Laravel-host example into the standalone platform bridge. | Use the displayed saas-shared-platform-console.php command and its detected platform/core paths. Confirm both scheduler and database queue recent-success evidence. |
| Scheduler fresh but database queue unhealthy | Queue execution or selected workspace background process failed. | Inspect the sanitized queue result and the named runtime’s private logs, correct database/storage/CLI configuration, and verify queue last success. Scheduler success alone does not prove queue health. |
| Needs review or browser request interrupted | Phase lacks verified evidence, or a bounded request/process stopped. | Retain the same job and journal. Fix the named error; the shared worker inspects/resumes recorded phases. Use available Continue/Refresh actions. Local owner jobs interrupted after claim require operator review, not blind replay. |
| Permission / open_basedir warning | PHP cannot access a required approved private platform/core/temporary path. | Have the host check website and CLI restrictions against the actual deployment roots and compatible release. Grant only the required paths and ownership permissions. Recheck the failing capability; do not use world-writable permissions or guessed /usr/bin paths. |
Plugin installation and existing-owner verification
| Symptom | Cause | Solution and verification |
|---|
| Plugin incompatible / ZIP rejected | Wrong core/PHP or archive structure. | Current source requires core 1.1.3 and PHP >=8.3 <9.0. Check the downloaded manifest. Upload the add-on ZIP with root plugin.json, not customer-delivery or platform-release. |
| Plugin folder already exists | Existing or partial install detected. | Inspect its actual state through Plugins and use the official cleanup/update procedure with a backup. Do not overwrite or uninstall an active SaaS installation just to retry upload. |
| Hosted add-on still shows old fields after local edits | The running installed plugin was not updated. This was observed during development. | Deploy the rebuilt compatible package to the actual host through the approved update process, then use the existing cache-clear action if needed. Confirm installed version/fields; local source changes do not update the server. |
| Ownership confirmation fails | Wrong current password/code, expired five-minute challenge, wrong installation proof path, changed session/identity or symlink. | Restart the challenge, replace storage/app/private/saas-owner-proof.txt using File Manager in the exact source installation, then confirm in the same session before expiry. Check HTTPS/configured URL and active verified owner eligibility. |
| Owner binding conflict after email/URL/key changes | Immutable owner binding no longer matches the trusted context. | Use the available protected owner-contact refresh when applicable or operator-reviewed recovery. Do not delete/edit the binding or select another administrator to take over. |
| Symptom | Cause | Solution and verification |
|---|
| Trusted runtime release not configured | Existing-owner shared preview has no configured private signed runtime artifact. | Operator supplies the verified artifact/checksum and private platform root using the documented configuration. The short browser form/add-on ZIP alone cannot supply the separate runtime. Rerun preflight. |
| Platform database/schema check fails | Source DB reused, dedicated DB configuration incorrect, or release/schema not current. | Verify the separate platform connection and named schema requirement. Ask the operator to review the matching release’s explicit schema-update procedure. No ordinary troubleshooting page should silently run migrations. |
| Changed/missing recorded migration | Applied migration file/hash differs from the recorded ledger. | Restore the exact matching release history; a new corrective migration belongs in a new file. Do not rename recorded files, delete ledger rows or run business migrations on the platform DB. |
| New settings/record fields absent or decoded incorrectly | Schema/release mismatch or incompatible persisted field positions. | Verify code and dedicated schema versions together. Corrective migrations/relational decoding repairs must preserve existing fields and appended positions. Operator approval is required for any schema work; refreshing alone is not a repair. |
| Signature, fingerprint or review digest mismatch | Delivery/publisher/request changed or damaged. | Stop installation, obtain the trusted matching signed delivery, confirm the publisher through a separate trusted source, and regenerate the review when appropriate. Do not bypass signature checks. |
Email, invitations and owner login
| Symptom | Cause | Solution and verification |
|---|
| Verification/readiness/invitation email missing | SMTP config/sender DNS, spam, failed bounded outbox attempt, or workspace not ready. | Check the intended recipient, Settings → Email test, sender authentication, spam and scheduler/outbox status. Fix transport and use the available resend action within its limit. Verify receipt of the latest message. |
| Link/code expired or already used | Old or consumed one-time invitation/code. | Request the current link/code through its supported resend flow and use the latest message. Never post the link/token to support. |
| Manually created owner expects an invitation/password flow | Manual activation already created the owner with the entered password. | Use that owner credential path, then normal password recovery where available. Self-signup activation and platform-owner invitations are separate flows. |
| Owner password rejected | Password policy or mismatch. | Use at least 10 characters and at most 72 bytes with a letter, number and symbol; repeat exactly. Correct timezone/country/currency/store code and other highlighted fields too. |
VPS installer and update recovery
| Symptom | Solution |
|---|
| No installation / multiple installations found | Verify the supported web root and intact required files. For ambiguous installations, use a reviewed selection procedure; do not invent a path or change another site. |
| Interrupted signed launcher job | Follow the supplied release’s resume instructions using the same pinned delivery/request. The guide’s launcher is sudo bash install-hyper-pos-saas.sh. Review the existing job before another run. |
| Tenant update failed while others passed | Inspect that tenant’s receipt, backup reference and named failure. Preserve successful independent receipts and follow the reviewed tenant retry/rollback path. |
| Backup/rollback evidence unavailable | Do not claim recoverability. Locate the verified current backup/catalogue and matching runtime binding, then use the approved recovery procedure. |
Information to include in a support request
Include the exact visible error/code, stage, timestamp/timezone, hosting mode, core/add-on version, web and CLI PHP versions, sanitized scheduler/queue/readiness status and the actions already tried. Screenshots should use test data with secrets fully covered.
Keep passwords, database/SMTP credentials, purchase codes, proof values, invitation URLs, gateway/webhook secrets, APP_KEY, SSH keys, raw .env files and customer backups out of support messages. Share logs only after removing sensitive values.
For the full ordered procedure, return to workspace setup or existing-installation conversion.