Hyperclay Local
  1. Hyperclay Local
  2. Docs
  3. Reference
  4. Troubleshooting

Troubleshooting

Fix common installation, port, folder, saving, and performance issues in Hyperclay Local.

Use these checks to resolve common installation, port, folder, saving, and performance problems in Hyperclay Local. You can also inspect recent logs at any time from the popover under Options > View Sync Logs and Options > View Error Logs (see Files the app writes).

Installation issues#

macOS “App is damaged” error#

If macOS Gatekeeper reports that the app bundle is damaged after downloading, clear the quarantine attribute in Terminal:

Shell
xattr -cr "/Applications/HyperclayLocal.app"

If your bundle in /Applications is named Hyperclay Local.app with a space, run:

Shell
xattr -cr "/Applications/Hyperclay Local.app"

Windows SmartScreen warning#

If Windows Defender SmartScreen displays an unrecognized-app prompt when launching the installer, click More info and then click Run anyway.

Linux permission denied#

Make the downloaded AppImage executable before launching it:

Shell
chmod +x HyperclayLocal-*.AppImage

For a specific version such as 1.32.0, run:

Shell
chmod +x HyperclayLocal-1.32.0.AppImage

Runtime issues#

Port 4321 or a team port is already in use#

When another program is listening on your personal folder’s port (4321) or a team folder’s port, the popover shows Can’t serve and the folder card reads Not served. Another program has :<port>. (see Status messages explained and Folders and ports).

  • Stop the other process using that port (or wait for it to finish), then click Retry on the folder card.
  • For a team folder, click Use port <n>… on the folder card and click Move to switch that folder to the next available port. Your personal folder always stays on port 4321.

Folder selection not working or “Folder not available”#

  • Ensure you have read and write permissions for the folder.
  • Choose a folder inside your home directory. Hyperclay Local refuses your home directory itself and any folder outside it with Folder not available (Choose a folder inside your home folder.).
  • Choose a folder that does not sit inside or contain another served folder (That folder overlaps <path>.).
  • If you are setting up a team folder, the folder must start empty (This folder isn't empty. A team folder has to start empty.) and have enough free disk space for the download.
  • Restart the app if the native folder picker dialog does not appear.

Opening a file from Finder or Explorer fails#

  • <file> is outside your Hyperclay Local folders.: Hyperclay Local serves only your personal folder and your team folders. Move the file into one of those folders, or click Show Personal Folder or Open in HTML Clay (see Open With).
  • Files inside hidden folders are not served.: Move the file out of any dot-prefixed folder (such as .hyperclay/ or .trash/).
  • Port <port> is in use by another program.: Resolve the port conflict on the folder’s card in the popover, then open the file again.

Server won’t start#

  • Make sure the server switch in the popover is turned on (Turn server on).
  • Check that the selected folder still exists on disk and contains readable files.
  • Ensure the folder path does not point to an unmounted drive or broken permissions.
  • Re-select your personal folder from Options > Change Personal Folder….

Documents won’t save#

  • Open the browser developer console and check the network response for /_/save.
  • Confirm you opened the document over HTTP (http://localhost:4321 for your personal folder or http://localhost:<port> for a team folder, or inside the workspace window), not as a file:// URL.
  • Check that the request meets the loopback Host and Origin rules in Rejected requests.
  • Verify that the document loads ClayJS or sends a valid POST /_/save request (see Make documents that save and Saving and stale-write protection).

Performance issues#

App feels slow#

  • Hyperclay Local runs an Electron process alongside local servers and file watchers. Close other resource-intensive applications if your machine is under heavy CPU or disk load.

High memory usage#

  • Electron apps use more memory than minimal native utilities.
  • Memory usage of around 100 to 200 MB is normal.
  • Restart the app from Options > Quit if memory usage grows excessively over a long session.