How to troubleshoot Salon Booking OS

Never paste passwords, database credentials, license keys, the contents of config/app_local.php or any key into a support request or a chat. Describe what you see instead.

Installation #

Every page sends me to /install. Until the installation finishes, every page goes to the installer — that is expected. After it finishes, every /install address answers “Already installed” by design; there is no reset or reinstall route.

A page names the site’s address instead of showing the site. The site was opened at another address than the one entered at installation — a temporary address from your host, for example. (Its www. or bare-domain counterpart is sent on to the right address by itself.) Open the address the page names. To move the site to a new address, follow Moving to another address in Installation.

The installation stopped part way. Use Start over on the installer’s page: it removes the installation’s progress and the configuration file it wrote. It never touches the database; empty the database it names before you install again.

The API answers https_required although the site uses HTTPS. The site sits behind a proxy or a CDN that ends HTTPS, and it does not trust that proxy yet. Add the proxy’s address to OsDot.trustedProxies — see Behind a proxy or a TLS terminator in Installation — and restart PHP if your host’s OPcache does not check file times.

The web server shows its own “Not Found” page, or a list of files, instead of the installer. The site’s document root is not the application’s webroot folder, or webroot/.htaccess is missing (some FTP programs hide or skip files whose names start with a dot). Point the document root at webroot (see Where the web root goes in Installation) and upload webroot/.htaccess again. Never point it at the application’s main folder or at public_html with the application inside.

“The setup token file could not be created”. Make the storage/ folder writable for the web server user and reload the page. If the file exists but is empty or malformed, delete it and reload.

“Too many attempts from your address”. Wrong setup tokens are paused for a few minutes. Wait for the time shown, then paste the token again.

The site shows an error before the installer appears. The application needs PHP 8.3 or later and stops at once on an older PHP. Select PHP 8.3 or later for the site in your hosting control panel.

A PHP extension is not loaded. Enable it for the PHP version the site uses, then reload the Server requirements page.

The Database step refuses.

• Existing data — the database already holds tables. Use an empty database; the installer never overwrites data.
• Schema privileges — give the database user the privileges listed in Installation (TRIGGER is not needed).
• utf8mb4 support — the server must offer full UTF-8.

The Database step warns about my database version. Your series is past its end of life or not yet certified for this version. You may continue at your own risk by ticking the confirmation. The warning stays visible to the owner afterwards until the database runs a supported series. A version below the minimum is refused.

“This upload is not a complete package of this product”. The Package check phase found files missing or of mixed versions; it names what is wrong. Upload every file of the package again, then retry the phase.

The license key is refused during the installation (licensed edition). The phase says why; see the table in Software license. Nothing is written to the database before the key is accepted, so you can try again with the right key.

“About your salon” stops with an error. Language and formats must be an English locale with its region, such as en-US or en-GB; Salon’s country must be two letters, such as US, or empty. Correct the value and run the phase again. Both can be changed later: the language on System → Website settings, the country on Salon → Location.

media check-public reports FAIL or WARN. The web server does not apply the rules of the web root’s media/ folder. On Apache allow AllowOverride with at least Options AuthConfig FileInfo for the web root; on Nginx add the block shown in Installation. Run the check again.

Scheduled tasks and maintenance #

The cron jobs do not seem to run, or fail. The command-line PHP of many hosts differs from the website’s. From the site’s folder run php bin/cake.php upgrade check once (or as a one-off cron job) and check that it reports PHP 8.3 or later. See Scheduled tasks (cron).

A scheduled task reports “another run is in progress”. A previous run is still working. This is normal; the next run continues.

Every page answers with a maintenance message. The file storage/maintenance.flag exists. Remove it when your maintenance work is finished. Scheduled tasks are skipped, not failed, while it exists.

After restoring a backup, pages show a form error once or pending codes stop working. The restored database was used with a different application salt. Restore config/app_local.php from the same backup as the database. See The application salt.

Signing in #

Sign-in is refused for a while after several attempts. Repeated wrong passwords pause sign-in for that account and address. Wait and try again.

I have forgotten my password. The team sign-in page links to Forgot your password?. Once your site’s e-mail is set up, it sends a link to choose a new password to the address you sign in with; the link works for 30 minutes. Someone who signs in with a sign-in name gets a New setup link from the owner instead (their account under People). While the site’s e-mail is not set up, no link can be sent and the page says to ask the owner: the owner then sets the new password with the command below. If the owner’s own password is lost and no reset link can reach you, set a new password from your hosting’s terminal (SSH), in the site’s folder: run php bin/cake.php auth reset-password --email <the owner's e-mail address>, then type the new password when asked, twice. Never put the password on the command line. Every session of that account is signed out, and the change is recorded in the audit log. The command asks for the password as you type, so it cannot run as a cron job: if your hosting has no terminal, ask your host’s support to run it for you, or contact our support. Keep the owner’s password in a password manager.

“Two-step sign-in” is not in the owner’s menu. It needs a code sent by e-mail. Until your site’s e-mail is set up under System → E-mail (SMTP), the menu says “Two-step sign-in is not available yet: this site cannot send e-mail.” instead of showing the link. It is offered to owner accounts only (see Your team’s sign-ins).

The two-step code no longer arrives. Whoever runs your server turns the second step off from the hosting’s terminal, in the site’s folder: php bin/cake.php auth two-step off --email <the owner's e-mail address>. Then sign in with the password alone, fix the site’s e-mail, and turn two-step sign-in on again.

“Your sign-in has ended”. The administration area signs you out after 120 minutes without a request, and 12 hours after you signed in at the latest; signing out elsewhere ends it too. Sign in again: you return to the page you had asked for.

How do I give my staff or my manager their own sign-in? Open People → Add a staff member; they get a setup link to choose their password (see Your team’s sign-ins). Do not share the owner’s password.

E-mail and codes #

Nothing is e-mailed: no confirmations, codes, setup links or shop e-mails. Your site’s e-mail is not set up yet. Set it up under System → E-mail (SMTP) and choose Validate saved configuration (it checks that your mail server answers; it sends nothing). To see a real e-mail arrive, make a test booking with your own address. Until then:

• clients cannot confirm an online booking or a shop order with a code, and the website shows no My bookings link;
• Take bookings online cannot be turned on (below);
• in the shop, a guest’s checkout says “We cannot send codes at the moment: sign in to order, or contact us.”;
• Forgot your password? says to ask the owner, and the owner’s two-step sign-in is not offered.

Messages planned before the e-mail was set up are not sent later. Messages shows each message and what happened to it (see Messages, reminders, text messages and push).

The booking page says “Online booking is not open yet.” with “We confirm every online booking with a code by e-mail, and e-mail is not set up yet.” The site’s e-mail stopped being set up after you turned on online booking. Check System → E-mail (SMTP) and send its test message.

Online booking #

“Take bookings online” cannot be turned on. The button on Front desk → Online booking stays unavailable with “Set up e-mail first: clients get their booking codes by e-mail.” Set up the site’s e-mail first (above). Only the owner opens this page.

Clients can’t book online. Check these in order (see Booking online and First admin and configuration):

• Front desk → Online booking says “The site takes bookings online”. Until it does, clients book through the front desk (Front desk → New booking, or a walk-in), and the website’s header offers “Call to book” with the phone from Salon → Location, or “Contact us” when no phone is set there.
• The service has Bookable online ticked (Salon → Services), and at least one staff member who does it has Clients can book … online ticked and working hours (Salon → Staff).
• The time is inside the booking rules: the minimum notice and how many days ahead clients can book online (System → Website settings).

The website has no “My bookings” link. It shows while the salon takes bookings online and the site’s e-mail is set up: clients sign in to it with a code sent by e-mail (or with Google, once set up). The team signs in at /login, linked as Team sign-in in the website’s footer.

Google sign-in #

Saving System → Google sign-in is refused.

• “Use a valid Google web client ID.” — paste the client ID of a web client of your Google Cloud project; it ends in .apps.googleusercontent.com.
• “Enter valid email domains without @ or wildcards.” — in Allowed e-mail domains, write domains such as example.com, separated by commas, or leave the field empty to let every client continue with Google.

Clients see “Signing in with Google is not offered here at the moment. Sign in with a code instead.” Google sign-in is not set up: enter the client ID and the client secret under System → Google sign-in.

Clients see “Google could not complete sign-in. Please try again.” Check the client ID and the client secret under System → Google sign-in, and that your Google web client lists, as an authorised redirect address, the address that page shows in its Google client ID field.

Clients see “The Google sign-in request expired. Try again.” The sign-in with Google took longer than 10 minutes, or was interrupted. The client starts again from the sign-in page.

A client sees “This e-mail address already has an account here. Sign in with a code sent to it instead.” By design, an address that already has an account is never joined to a Google account by its e-mail address. The client signs in with a code.

A client sees “Signing in with Google is not offered for this e-mail address.” The address is not in your Allowed e-mail domains. Add its domain, or empty the field.

The shop #

The shop is not on my website. “Shop” appears in the website’s header and footer only while a product is on sale: its status Active (on the website with an active variant) under Shop → Products, with at least one active variant. A product in a hidden category does not count.

Clients are not offered “Pay when you collect”. Turn on Pay at pickup (pickup orders) under System → Payment options; clients see it as “Pay when you collect” for orders they collect at the salon. Pay on delivery is allowed per delivery zone, under Shop → Delivery.

A shop order paid in person cannot be marked collected. An order to pay when collected (or on delivery) is unpaid until it is handed over. On the order’s page (Shop → Shop orders), Collected (or Delivered) records the payment taken and hands the order over in one step. Then:

• “This order is not paid yet: someone who records payments hands it over.” — your role does not include Record a payment taken at the salon. The owner and the manager / front desk hold it by default.
• “Another staff member records a payment for your own order.” — nobody records a payment for an order they placed themselves. Ask a colleague.

The salon gets no e-mail about new orders, returns or low stock. These go to the Public contact e-mail under Website → Business profile (it is also the site’s contact e-mail), and only once the site’s e-mail is set up. Without a public contact e-mail, the salon gets none of them.

Only one low-stock e-mail came, although stock is still low. A variant’s low-stock e-mail is sent once, when the units available fall to its low-stock level. It is sent again only after the stock has risen above that level and fallen to it again. Shop → Stock lists the low variants first, marked “low”.

Software license (licensed edition) #

Only the licensed edition has a software license. See Software license for each status.

“New licensed work is paused.” on System → Software license. The license is Not activated, Rejected by the license server, or Not confirmed for too long (grace exhausted). Activate your key on that page, or choose Check now once the license server can be reached again. Existing records stay readable meanwhile.

The menu shows “Software license (attention)”. The status is not Active: open the page. Active — renewal problem (grace period) means the daily confirmation did not succeed; the site keeps working until the grace period shown on the page ends. Check that the scheduled task license renew runs (see Scheduled tasks (cron)) and that your server can reach the internet over HTTPS.

“This key has no activation left. Deactivate another installation first.” Release the activation of an installation you no longer use, on its own Software license page (Deactivate this installation), then activate here.

Administration #

A page answers “forbidden”. Your role does not include the permission the page needs. See Roles and permissions.

“My day” or “My schedule” is missing (or, for the Staff role, the Calendar). Your account is not linked to a staff member. The owner links it on Salon → Staff sign-in.

Owner-only settings keep asking for my password. A confirmation lasts 10 minutes, then the page asks again. This is intended.

Saving asks for my password again. Saving the Location page, the website’s brand or business profile, publishing a legal page, switching the website to another theme, or changing an account’s state or roles asks for your password when you last signed in or confirmed it more than 10 minutes ago. What you typed is kept: confirm your password and it is saved as you typed it. Two things cannot be kept and are named on the page — a file you chose (choose it again) and a provider’s secret key (type it again).

Business settings shows only a few rules. It lists only the rules the owner hands over. The others are on System → Website settings (owner only). Below them, Where each detail is changed shows where each of the salon’s details is set.

Times are shown in 12-hour (or 24-hour) form. Change Language and formats on System → Website settings: en-US gives 12-hour times, en-GB 24-hour.

Times are in the wrong time zone. The salon has one time zone, set on Salon → Location; appointments, the calendar and every date in the administration area use it. Correct it there. The time zone row on Website settings only shows where it is managed. A person who chose their own time zone under My profile sees the dates of their account’s pages in it; appointments stay in the salon’s time zone. Appointments are kept as moments in time: after a zone change every existing appointment shows at a different local time, so check them and move any that must stay at their old clock time.

A missing page shows “Page not found” in the website’s theme. That is the website’s own “Page not found”, with its header, menu and footer and a way back to the home page. (After the installation /install answers “Already installed” instead, in the installer’s own look.) In the administration area a missing page keeps the administration area’s look, with a way back to it.

The website shows an old address or phone number. The website’s business details are copied from Salon → Location each time it is saved. Correct them there and save; an edit in the website’s business profile is replaced at the next save of the Location page.

Front desk #

A booking is refused because the time is taken. The staff member already has an appointment then. Choose one of the Next free times the form offers.

The phone number is refused. Desk and phone bookings need a valid phone number. Type it with the country code (for example +44 20 7946 0018). A number without the country code is read only when the salon’s country is set on Salon → Location.

Clients are not getting confirmations or reminders. Check these in order (see Messages, reminders, text messages and push):

• Your site’s e-mail is set up under System → E-mail (SMTP). Booking e-mails need it; those planned before it was set up are not sent later. With neither e-mail nor text messages set up, the booking form says “Nothing goes out to clients yet”.
• The appointment has the client’s e-mail address, or a mobile number with text messages set up. Otherwise the booking form warns “This client won’t receive confirmations or reminders.”
• Reminders need a saved rule under Front desk → Reminders; after a change, the coming appointments’ reminders are planned again by the next run of communication work.
• The scheduled task communication work runs every minute (see Scheduled tasks (cron)).
• Messages shows each message and what happened to it.

“Any available” finds nobody outside working hours. “Any available” only places appointments inside staff members’ working hours. Name a staff member yourself; if you may override soft rules, give a reason and choose Book anyway.

I cannot reopen a completed appointment or revert a no-show. Both are possible only on the appointment’s day and need the manager’s permission Reopen a completed booking or revert a no-show the same day ….

The history says “arrival not marked”. The appointment was completed from the end-of-day list without being marked as arrived first. This is recorded on purpose.

On a phone, the calendar cuts off an appointment’s details. Scroll to the day’s list below the grid; it shows every appointment in full.