# Troubleshooting

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

Source: https://hyperclaylocal.com/docs/troubleshooting/

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](https://hyperclaylocal.com/docs/files/)).

## 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:

```bash
xattr -cr "/Applications/HyperclayLocal.app"
```

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

```bash
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:

```bash
chmod +x HyperclayLocal-*.AppImage
```

For a specific version such as `1.32.0`, run:

```bash
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](https://hyperclaylocal.com/docs/status-messages/) and [Folders and ports](https://hyperclaylocal.com/docs/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](https://hyperclaylocal.com/docs/guide/team-folders/), 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](https://hyperclaylocal.com/docs/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](https://hyperclaylocal.com/docs/guide/workspace/)), not as a `file://` URL.
- Check that the request meets the loopback `Host` and `Origin` rules in [Rejected requests](https://hyperclaylocal.com/docs/rejected/).
- Verify that the document loads [ClayJS](https://clayjs.com/docs/) or sends a valid `POST /_/save` request (see [Make documents that save](https://hyperclaylocal.com/docs/making-malleable-documents/) and [Saving and stale-write protection](https://hyperclaylocal.com/docs/saving/)).

## 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.