Troubleshooting Guide

Solutions to the most common issues with Sharoo

This guide covers the most common issues you can encounter while installing, configuring, and using Sharoo.

Sharoo is a macOS app that:

  • Installs a small PHP “Server Kit” on your web hosting via SFTP.
  • Uploads files/folders to your server via SFTP.
  • Generates a public download link (and QR code) that points to download.php on your server.

For support, use the contact form

1) Setup & Server Compatibility (Install and Verify)

During setup, Sharoo performs:

  • SFTP connection (to upload the Server Kit).
  • PHP verification via GET <Base URL>/status.php.
  • .htaccess verification via GET <Base URL>/htaccess-test.txt.

If any of these checks fail, setup may stop.

1.1 “Invalid SFTP host.”

What it means: The SFTP host field is empty or not a valid host.

How to fix: Check the host value (example: ftp.yourdomain.com or your server IP). Do not include http:// or https:// in the SFTP host.

1.2 “Unable to reach the SFTP server. Check the host, port, and your Internet connection.”

What it means: Sharoo could not open a TCP connection to the SFTP server.

Common causes: Wrong host, wrong port (default is 22), SFTP blocked by firewall or network restrictions.

How to fix: Verify host and port with your hosting provider. Try from another network. If your hosting uses a custom SFTP port, enter that value in Sharoo.

1.3 “Unable to establish a secure connection to the SFTP server.”

What it means: The SSH handshake could not be completed.

Common causes: Server does not actually provide SFTP on the selected port, or misconfigured SSH/SFTP service.

How to fix: Confirm you’re using SFTP (SSH File Transfer Protocol), not FTP/FTPS. Confirm the port is the one your hosting uses for SFTP.

1.4 “Authentication failed. Check your username and password.”

What it means: The server rejected the username/password.

How to fix: Double-check credentials in your hosting panel. If your hosting account uses a specific SFTP username, use that one. If your hosting uses IP allowlisting for SFTP, ensure your current IP is allowed.

1.5 Setup asks to overwrite an existing sharoo/ folder

What it means: A sharoo/ folder exists on the server but kit.json is missing. Sharoo may offer to reinitialize that folder.

Important: Overwriting may delete files inside that sharoo/ directory.

How to fix safely: If you are not 100% sure, choose Cancel. Pick a different remote base path so Sharoo creates a fresh sharoo/ folder.

1.6 “Invalid Public Base URL.”

What it means: The Base URL is empty or not a valid URL.

How to fix: Use a full HTTPS URL. Example: https://example.com/sharoo or https://example.com/some/subfolder/sharoo.

1.7 “Public Base URL may be wrong (404).”

What it means: status.php could not be found at the Base URL.

Common causes: The SFTP remote path and the public Base URL point to different folders. The Base URL is missing a path segment.

How to fix: Ensure the Base URL ends up pointing to the same folder where Sharoo uploaded the Server Kit. In Sharoo, the Server Kit is installed under <remoteBasePath>/sharoo/, so the Base URL must resolve to that same location.

1.8 “Unexpected response from status.php (invalid JSON).”

What it means: Sharoo received a 200 response, but it wasn’t valid JSON.

Common causes: PHP is not executing correctly on the server, or the server returned an HTML error page.

How to fix: Open https://<your-base-url>/status.php in the browser. It must return JSON containing "ok": true. If you see HTML or PHP source, PHP is not configured correctly.

1.9 “HTTPS is required.” (during setup or upload)

What it means: Sharoo requires the Base URL to work over HTTPS.

How to fix: Enable SSL/TLS on your hosting. Make sure your Base URL is reachable as https://....

1.10 “Security check failed: .htaccess is not enforced on your server. Setup cannot continue.”

What it means: Sharoo requested htaccess-test.txt and your server served it successfully, which indicates .htaccess rules were not applied.

Why this matters: Sharoo uses .htaccess hardening to reduce accidental exposure of sensitive files.

How to fix: Use a hosting/environment that supports Apache .htaccess rules. Ensure your chosen installation directory allows overrides (AllowOverride). Nginx-only hosting without .htaccess compatibility will not pass.

1.11 “Security check failed: unable to verify .htaccess support.”

What it means: Sharoo could not reliably test htaccess-test.txt.

How to fix: Recheck Base URL. Try again from a stable connection.

1.12 Server returns a CAPTCHA or security challenge

What it means: Some hosting providers may respond with a CAPTCHA or security challenge when too many HTTP requests are made in a short period of time. When this happens, Sharoo cannot function correctly because the server is blocking automated access to status.php and other Server Kit endpoints.

How to verify: Open https://<your-base-url>/status.php in your browser. If you see a CAPTCHA page instead of the expected JSON response, your hosting is actively rate-limiting or challenging automated requests.

How to fix: First, open https://<your-base-url>/status.php in your browser and solve the CAPTCHA manually. Then wait a few minutes for the rate-limit window to fully reset, and retry using Sharoo. If the issue occurs frequently, consider contacting your hosting provider to ask if they can whitelist or relax rate-limiting for your Server Kit endpoints, or switch to a hosting plan with more generous request limits.

2) Using Sharoo after setup

2.1 “Your server kit is outdated… Required: X” (when uploading)

What it means: Before upload, Sharoo checks status.php and requires a minimum Server Kit version.

How to fix: Go to Settings → Server. Click Install or Update (or Update Server Kit if shown). Then retry the upload.

2.2 ZIP downloads are not available

What it means: status.php reports zipAvailable: false if the PHP ZipArchive class is missing.

Impact: Recipients may not be able to download a full multi-file transfer as a single ZIP. Individual file downloads still work.

How to fix: Ask your hosting provider to enable the PHP ZIP extension (ZipArchive).

3) Upload issues

3.1 “Please complete Setup first.”

What it means: No server configuration/password is saved yet.

How to fix: Complete the Server setup and verification first.

3.2 “Please select at least one item.”

What it means: You started an upload without selecting files/folders.

How to fix: Add at least one file or folder.

3.3 Upload fails because of selection limits

Sharoo enforces limits from Settings → Limits: maximum number of files, maximum total size.

How to fix: Reduce the number of selected items or total size, or adjust limits in Settings.

3.4 “Unable to read the selected file.” / file picker errors

What it means: macOS did not grant access to read a file/folder, or the item became unavailable.

How to fix: Re-select the file/folder. Avoid selecting items on disconnected external drives or network volumes.

3.5 Password validation errors

Sharoo enforces strong passwords. Common rules: minimum length, no spaces, ASCII-only, must include uppercase, number, and special character.

How to fix: Use a password like Sharoo2026! (example format only).

3.6 “No Internet connection.” (during verification)

What it means: Sharoo could not reach your Base URL to verify status.php.

How to fix: Connect to the Internet and retry.

4) Download page issues (Recipients)

These issues happen on your server’s Transfer Page (download.php).

4.1 “This link has expired”

What it means: The Transfer expiration time was reached.

How to fix: Create and share a new Transfer.

4.2 “Download limit reached”

What it means: The Transfer reached the maximum number of downloads.

How to fix: Create and share a new Transfer with a higher max-downloads value.

4.3 Password-protected Transfers: “Wrong password” / “Too many attempts”

What it means: The recipient entered the wrong password. After several failures, the Server Kit temporarily blocks new attempts.

How to fix: Wait and try again with the correct password. Copy/paste exactly, no leading/trailing spaces.

4.4 Recipient has to re-enter the password repeatedly

What it means: The Server Kit uses a functional cookie to remember successful password entry. If cookies are blocked, the cookie may not persist.

How to fix: Allow cookies for the site hosting the transfer. Use a normal browsing window.

5) History, Sync, and deletion issues

5.1 “Sync from server” shows fewer items than expected

What it means: Sharoo reads transfer information directly from your server via SFTP. If transfers were deleted manually or server-side metadata was changed, Sharoo may not display them correctly.

How to fix: Ensure your server settings still point to the same location. Avoid manually renaming or moving files inside the Sharoo folder. If you recently changed server settings, run security checks and try syncing again.

5.2 Deleting a transfer removes files permanently

What it means: “Delete from server” removes the transfer’s files from your server.

How to fix: There is no undo. Only restore from your own server backups if available.

6) What to include when reporting an issue

When you contact support, include:

  • Your Sharoo app version.
  • Your Server Kit version.
  • The exact error message shown by Sharoo.
  • Which step failed: SFTP connect, PHP verification, .htaccess verification, Upload, Sync/Delete.
  • The Base URL you configured (you can redact your domain, but keep the path structure).

Support contact form