--- title: Handyman Booking OS troubleshooting description: "Problems you may meet with the installer, background tasks, e-mail and codes, online booking, the workers' app and payments, the known limits in version 1.0, and their safe fixes." url: "https://osdots.com/docs/handyman-booking-os-troubleshooting/" updated: "2026-11-03" category: Product Documentation / Handyman Booking OS by OsDot™ --- # Handyman Booking OS troubleshooting 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](https://osdots.com/docs/handyman-booking-os-server-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](https://osdots.com/docs/handyman-booking-os-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](https://osdots.com/docs/handyman-booking-os-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](https://osdots.com/docs/handyman-booking-os-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](https://osdots.com/docs/handyman-booking-os-support-and-services/).