Handyman Booking OS troubleshooting
Table of Contents
Start with two pages: Business → Messages (what happened to every message) and System → Before you go live (what the server still needs). Never share a password, a key or the content of config/app_local.php when you ask for help.
The installer #
| What you see | What to do |
|---|---|
| The setup token is refused | Copy the whole content of storage/install/setup-token.txt (one line) from your server, with no space before or after. After 5 attempts in 15 minutes, wait and try again. |
| "The setup token file could not be created" | Make the storage/ directory writable for the web server's user, then reload the page. |
| The requirements page shows a failed check | Ask your hosting to add what the check names (a PHP extension, the PHP version, URL rewriting, HTTPS); see System requirements. |
| The database step refuses the database | It must be empty, and its user needs the rights to create tables. Use a new empty database. |
| The installer stops with an error 500, or says the maximum execution time was exceeded | PHP max_execution_time: at least 120 seconds during installation. Raise it in your hosting's PHP settings, then reload the page. If the installer does not continue, begin again with Start over, as in the next row. |
| You want to begin again | Until the installation is finished, Start over on the install step; it never deletes tables, so use a new empty database or empty this one in your hosting's control panel. |
Nothing happens on time (reminders, review requests, retries) #
The site's background work runs from one scheduled command. Check that the command from System → Before you go live is in your hosting scheduler, every minute (or every 5 or 15 minutes where your host allows no more), exactly as the page shows it. With a slower schedule, reminders and retries simply run later.
E-mail and codes #
- Nothing is e-mailed. Business → Messages shows such messages as Failed (Email unavailable). Set up System → E-mail (SMTP) and press Validate saved configuration (Integrations).
- A message is marked "Unknown — check before sending again". It may have arrived: check with the person before sending it again.
- A customer gets no code. A code stays valid 10 minutes; a contact can ask for one code a minute, 5 an hour and 10 a day, and a network address for 10 an hour of each kind of code (signing in, booking, a contact request, your own second step), so customers on one shared network cannot use up your own code; after 5 wrong entries a code is void. These are One-time codes rows in System → Website settings.
- Estimate requests reach nobody. Set your public contact e-mail under Website → Business profile.
Online booking #
- Customers cannot book. Work → Online booking must say that the site takes bookings online, and Business → Hours, workers and services must show every item of What online booking needs. While online booking is off, the app leaves out Book a job and tells a customer who starts a booking that online booking is closed; on the website every booking step says Online booking is closed, with your phone number and a button to call it.
- No times are offered. Check the business hours, the worker's own Schedule under People → Workers, Closures and holidays, the minimum notice (120 minutes by default; for jobs at an address, the longer of the two) and how many days ahead customers can book (60 by default).
- A customer's area is missing. Add it under Business → Jobs at the customer's address → Areas you serve.
- A customer cannot move a job online. Online moves end at the deadline in System → Website settings (by default 24 hours before the start, and two moves per job); after it, the job's page asks them to call you. Cancel this job stays on the page.
The workers' app #
- A worker sees no jobs. Link their account to their worker record under People → Workers' sign-in; the account needs the Worker role.
- A worker cannot see the address or the phone. They show only around the visit; until then the job says "Address hidden".
- A job cannot be completed. The business asks for proof pictures (one by default) and, if switched on, the customer's completion code (System → Website settings, the Jobs rows). After too many wrong tries the code locks: the office completes the job.
Payments #
- A provider is not offered at checkout. Its page under System must be enabled and validated, and the provider must accept your site's currency.
- A payment stays unconfirmed. Check that the webhook address the provider's page shows is registered in the provider's dashboard, with its secret or ID copied back. Money → Reconciliation shows what is still being confirmed and each provider's last webhook.
- "Back to the app" does not open the app after a payment. System → Payment options needs your app's iOS App ID, or its Android package name and signing certificates' SHA-256 fingerprints. Until then the customer closes the page and returns to the app.
Pictures #
- A picture cannot be saved. Give it its Alternative text: it is required with a picture.
- Pictures do not show on an Nginx server. Add the media location block, then run
php bin/cake.php media check-public(see System → Before you go live).
After an update #
If System → Updates says The update did not complete, the site stays in maintenance: see Updates and backups.
Software license #
- The menu says "Software license (attention)". Open System → Software license: activate with the key from your purchase, or press Check now.
- "New licensed work is paused". The license is missing, refused or unconfirmed for too long. Check that the Confirm the license scheduler line runs and that the server can reach the license server (see Software license).
Known limitations in version 1 #
- The slideshow and the worker's screens use a few fixed colours that do not follow your colour changes.
- Known in version 1.0: the app may ask you to sign in again when you reopen it after a while. A fix is planned for the next version.
Getting help #
See Support and services.
