- Hyperclay Local
- Docs
- The app
- Status messages explained
Status messages explained
Every folder card status, popover readout, banner, and notice message in Hyperclay Local, what each one means, and what to do.
Hyperclay Local reports the state of your local servers, sync sessions, and app updates in four places: top-of-popover banners, the Serving and Sync status lines, per-folder cards (each with a short line under the folder name and a longer message in the card’s hover tooltip or single-folder status readout), and the Notices and Activity tabs.
Popover banners#
At most one account-wide banner appears at the top of the popover’s home view, alongside any app update banner:
| Banner text | What it means | What to do |
|---|---|---|
| Sync key no longer works. (with Reconnect →) | Your hyperclay.com API key expired or was revoked. | Click Reconnect → (or open Options > Sync Key…) and enter a valid API key. |
| hyperclay.com needs an update before sync can run. Folders are still served. | The server on hyperclay.com is on an older protocol version than your app requires for sync. | Keep working locally; sync resumes automatically once hyperclay.com updates. |
Restart to update to v<version> | A new version of Hyperclay Local has finished downloading and can install in place. | Click the banner. It changes to Finishing sync…, waits for active sync and saves to finish, and restarts into the new version. |
Update v<version> available | A new version of Hyperclay Local is out, and your current copy cannot replace itself in place. | Click the banner to open https://hyperclaylocal.com/ and download the new installer. |
Serving and Sync switch readouts#
These status lines appear next to the Serving and Sync switches in the popover:
| Readout | Detail line | What it means | What to do |
|---|---|---|---|
| Serving | at localhost:<port> or <n> folders on this computer | The local HTTP server is running. | Click the address or Open workspace to open your documents. |
| Starting… | Turn on to open your documents | The local server is starting up. | Wait a moment for the server to bind its port. |
| Not serving | Turn on to open your documents | The Serving switch is turned off. | Turn on the Serving switch (Turn server on) to serve your folders locally. |
| Can’t serve | Not served. Another program has :<port>. | Another program is already listening on the folder’s port. | Stop the other program and click Retry, or click Use port <nextPort>… on a team folder. |
| Not synced | Only on this computer | No sync key is saved. | Click Connect sync → to connect your hyperclay.com account, or leave it off to work locally. |
| Sync off | Changes stay on this computer | A sync key is saved, but the Sync switch is turned off. | Turn on the Sync switch to resume syncing. |
| Sync on | Each folder shows its own state | Multi-folder readout when global sync is enabled. | Check each folder row for its individual status. |
| Syncing | Syncing 1 file…, Syncing <n> files…, or Syncing… | Single-folder readout while files are transferring. | Wait for the transfer to finish. |
Synced as @<username> | Up to date (or relative time) | Single-folder readout when all files are in sync. | No action needed. |
| Not synced | Folder’s full status message | Single-folder readout when the folder is paused, offline, in conflict, has blocked files, or hit an error. | Follow the guidance for that folder message in the tables below. |
Folder card states: normal and local-only#
Each folder card displays a short line under the folder name (except when more than four folders are listed, where synced rows hide the timestamp for compactness) and a full message in the hover tooltip:
| Short card text | Full message (tooltip and status detail) | What it means | What to do |
|---|---|---|---|
synced <time> ago | synced | All syncable files in this folder match hyperclay.com. | No action needed. |
syncing 1 file… / syncing {count} files… / syncing… | Same as short text | Sync is uploading or downloading changes. | Wait for the transfer to finish. |
| not synced | Served locally. Connect to sync it with hyperclay.com. | The folder is served on localhost, but no sync key is connected. | Click Connect sync → if you want to sync this folder with hyperclay.com. |
| sync off | Sync is off for all folders. | The global Sync switch is turned off. | Turn on the Sync switch in the popover to sync changes. |
local only · was {team} | Disconnected from {team}. Still served here; nothing syncs. | You disconnected this team folder from hyperclay.com. | Keep using it locally, or choose Remove Folder… in its ⋯ menu to stop serving it. |
| not on this computer | You’re an editor on {Team}. Set up a folder to sync it here. | You have editor access on this team, but have not set up a local folder for it yet. | Click Set up → to choose an empty folder and start syncing. |
| viewers use the site | You’re a viewer on {Team}. Viewers open team documents on hyperclay.com. | You have viewer-only access on this team, so it has no local folder or port. | Click hyperclay.com ↗ (Open on hyperclay.com) to view the team’s documents on the web. |
Folder card states: attention required#
When a folder cannot serve or cannot sync cleanly, its card shows a second line with one of these states:
| Short card text | Full message (tooltip and status detail) | What it means | What to do |
|---|---|---|---|
Not served. Another program has :{port}. | Not served. Another program has :{port}. | Another program on your computer is using port {port} on 127.0.0.1. | Stop the other program and click Retry, or click Use port <nextPort>… on a team folder to move it to a free port. |
1 conflict / {count} conflicts | A file changed here and on hyperclay.com. Both copies are kept; see Notices. | A file was edited on both sides (or deleted on one side and edited on the other). | Open the Notices tab and choose Keep mine, Keep theirs, or Keep both. See Conflicts and deletions. |
| offline | Can’t reach hyperclay.com. Changes sync when you’re back online. | Hyperclay Local cannot reach hyperclay.com. | Keep working locally; changes sync automatically when your connection returns. |
1 file can’t sync / {count} files can’t sync | Stored on this computer. Too large for this plan to sync. | One or more attachments exceed your plan’s per-file upload limit. | Open the Notices tab to see the file size and limit. Shrink or remove the file, or upgrade your plan. |
| sync error | Last error message from sync (or sync error) | An unexpected error occurred while syncing this folder. | Check the Notices tab, or open Options > View Sync Logs and View Error Logs. |
Folder card states: paused sync#
When sync pauses on a folder, your local files remain on your computer and keep serving at localhost:<port>:
| Short card text | Full message (tooltip and status detail) | What it means | What to do |
|---|---|---|---|
| paused: you’re a viewer | You’re now a viewer on {Team}. Your files are still here and still served at localhost:{port}. Sync resumes if you’re made an editor again. | Your team role was changed from editor to viewer after you set up the folder. | Keep using the local copies, ask a team admin to restore editor access, or click Disconnect… / Remove Folder…. |
| paused: plan inactive | {team}’s plan isn’t active. Your files are still here and still served. Sync resumes when the plan is active again. | The team’s subscription on hyperclay.com is inactive. | Renew the team’s plan on hyperclay.com to resume syncing, or click Disconnect…. |
| paused: plan inactive | your hyperclay.com plan isn’t active. Your files are still here and still served. Sync resumes when the plan is active again. | Your personal subscription on hyperclay.com is inactive. | Renew your plan on hyperclay.com to resume syncing. |
paused: not on {team} | You’re no longer on {Team}. Your files are still here and still served. Sync resumes if you’re added back. | Your account was removed from the team. | Click Disconnect… to keep serving the folder as local-only, or Remove Folder… to stop serving it. |
| paused: team unavailable | {Team} was deleted or is unavailable on hyperclay.com. Your files are still here and still served. | The team no longer exists or is unavailable on hyperclay.com. | Click Disconnect… or Remove Folder…. |
| paused: reconnect | Your sync key no longer works. Reconnect to resume. | Your API key expired or was revoked. | Click Reconnect → in the top banner (or Options > Sync Key…) and enter a new key. |
| paused: no sync access | Your role on {Team} doesn’t allow syncing right now. Your files are still here and still served. | Your account does not have sync permission for this team. | Check your role on hyperclay.com or click Disconnect…. |
| paused: waiting for hyperclay.com | hyperclay.com needs an update before this folder can sync. It’s still served. | The hyperclay.com server needs a newer version before this folder can sync. | Wait for hyperclay.com to update; local serving continues meanwhile. |
| paused: folder missing | This folder isn’t there any more, so nothing syncs and nothing was deleted on hyperclay.com. Put it back, or Disconnect. | The folder on disk was moved, renamed, or deleted. No deletions were sent to hyperclay.com. | Move the folder back to its path to resume, click Disconnect… on a team folder, or use Options > Change Personal Folder… for your personal folder. |
| paused: set up again | This folder’s sync records belong to a different account or folder, so nothing syncs. Disconnect, then set it up again. | The .hyperclay metadata inside the folder does not match this account or folder. | Click Disconnect…, then set up the team in an empty folder. |
| paused: folder changed | This folder’s contents were replaced since it was set up, so nothing syncs and nothing was deleted on hyperclay.com. Put the original folder back, or Disconnect and set it up again. | The folder on disk was replaced with a different folder since initial setup. No deletions were sent to hyperclay.com. | Restore the original folder to resume, or click Disconnect… and set it up again. |
Notices, Activity, and system tray messages#
| Location | Message | What it means and what to do |
|---|---|---|
| Notices tab | <Folder>: <path> changed here and on hyperclay.com | A file has a sync conflict. Click Keep mine, Keep theirs, or (for two-sided edits) Keep both. |
| Notices tab | <file> is stored here but can’t sync: <size>, and this plan allows <limit> | An attachment is over your plan’s per-file upload limit. Click Show File to reveal it on disk. |
| Notices tab | <n> attachments were removed from uploads at once. They are kept on the server until you choose to delete them there or restore them here. | A bulk removal of attachments in uploads/ is held for confirmation. Click Delete on server or Restore here. |
| Notices tab | All quiet | There are no active conflicts, blocked files, or sync errors. |
| Activity tab | Transfers show up here | No files have been uploaded, downloaded, or deleted in the current session. |
| System tray tooltip | Hyperclay Local: <n> folders, <count> <state> | Summarizes the highest-priority folder condition (error, port taken, conflict, paused, offline, can't sync, syncing, not set up, or viewer). Open the popover to inspect the folder. |
| System tray menu | <Title> (not set up) / <Title> (port <port> in use) / <Title> (not served) | Shows why a folder in the tray menu is not currently serving at localhost:<port>. |