# Troubleshooting

> Error messages, dialogs, and HTTP responses you can encounter in HTML Clay, what causes each one, and how to fix it.

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

This page lists the error messages, dialogs, browser pages, and HTTP statuses HTML Clay can show, grouped by area.

## Starting up and ports

See [Opening files and addresses](https://htmlclay.com/docs/opening-files/) and [Configuration](https://htmlclay.com/docs/configuration/).

- **`HTML Clay can't start`: `Port N is in use by X (PID n).`** (or **`Port N is in use, and HTML Clay could not tell by which program. On Windows this can also mean the port sits in a range reserved by Hyper-V or WSL.`**)
  Another process is holding the port saved in `config.json`. Click **Quit It and Retry** (or **Retry**), or click **Use a New Port** to move HTML Clay to the next free port from its candidate list (`1212`, `4545`, `9797`, `3434`, `1111`).
- **`HTML Clay can't start`: `HTML Clay could not find a free port. It tried [1212 4545 9797 3434 1111] and 20 random ports on this computer, and every one was in use.`**
  Every candidate port and 20 random ports between `10000` and `32767` could not be bound on loopback. Check local firewall rules or Windows Hyper-V/WSL excluded port ranges, free a port, and launch HTML Clay again.
- **`HTML Clay now uses port N instead of M. Bookmarks with the old port stop working, and anything pages stored in the browser under the old address starts over.`**
  You chose **Use a New Port** when the previous port was busy. Update your browser bookmarks to use the new port number.
- **`[htmlclay] config.json is corrupt (...); saved it as ... and starting from defaults`**
  Printed to standard error when `config.json` contains invalid JSON. HTML Clay renames the broken file to `config.json.corrupt-<unix-time>` and resets to defaults. Inspect the backup file if you want to restore your previous settings.
- **Linux prompt error (`... Until then, a file opened from outside a trusted folder is refused, because the prompt that would allow it cannot be shown.`)**
  HTML Clay needs `zenity` or `kdialog` on Linux to display native permission dialogs. Install `zenity` or `kdialog` with your distribution's package manager, or open files from a [trusted folder](https://htmlclay.com/docs/guide/trusted-folders/).

## Opening files, addresses, and trusted folders

See [Opening files and addresses](https://htmlclay.com/docs/opening-files/) and [Trusted folders](https://htmlclay.com/docs/guide/trusted-folders/).

- **`HTML Clay can't open this file`: `<name> is outside your home folder. HTML Clay only opens files inside <home>.`**
  You opened a file located outside your user home directory. Move the file into a folder inside your home directory and open it again.
- **`HTML Clay is running / Each folder you open has its own address ending in .localhost. Nothing is served at this one.`**
  You navigated to bare `localhost:<port>`, `127.0.0.1:<port>`, or `[::1]:<port>`. Double-click a file in Finder or your file manager, or use the HTML Clay tray menu, so it opens at its `<slug>.localhost:<port>` folder address.
- **`Nothing is open at this address`**
  You opened a bookmarked `.localhost` address whose folder is not currently active. Double-click the file in your file manager to open it, or add its folder under **Trusted Folders** in the tray menu.
- **`This trusted folder needs approving again`**
  A trusted folder was moved, deleted, or replaced on disk, so its stored identity no longer matches. Open the tray menu and choose **Trusted Folders** then **Trust a Folder...** to approve it again.
- **`This file is outside this folder`** (HTTP `403`, header `X-HTMLClay-Error: outside-folder`)
  You navigated in the browser to a file path outside the folder served by the current `.localhost` hostname. Open that file from your file manager so HTML Clay serves it on its own folder address.
- **`Read access required`** (HTTP `403`, header `X-HTMLClay-Error: read-access-required`)
  A page tried to fetch or embed a file outside its permitted folder and read permission was not granted. Reload the page and choose **Allow Once** or **Trust This Folder** when prompted.
- **`Read-only view. This file was opened from a link.`**
  You reached a `.htmlclay` document by following a link rather than opening it from your file manager or a trusted folder. Click **Trust this folder** in the banner to make it editable, or double-click the file in your file manager. If the banner says **`This offer expired. Reload the page to ask again.`**, the 10-minute prompt token expired; reload the tab and click **Trust this folder** again.
- **`<dir> was not trusted. A page requested it, and it is one of your main personal folders...`**
  A page asked to trust a top-level personal folder such as `Documents` or `Desktop`. Pages cannot request trust for main personal folders. Move the file into a dedicated project folder, or add the folder yourself from **Trusted Folders** in the tray menu.
- **`<dir> was not added to your trusted folders. ... It stays readable until you quit. You can add it yourself from the HTML Clay menu.`**
  You declined the trust dialog or `config.json` could not be saved. Add the folder from **Trusted Folders** in the tray menu when you want permanent write access.

## Saving, uploads, and exports

See [Server endpoints and save protocol](https://htmlclay.com/docs/server/), [Uploads and assets](https://htmlclay.com/docs/uploads/), and [Export as zip](https://htmlclay.com/docs/export/).

- **`<file> had been changed outside this tab. Your version was saved; the previous one is in Backups.`** (HTTP `200` warning)
  Your save had no `If-Match` stamp and overwrote an external change on disk. You can restore the overwritten copy from [Backups and recovery](https://htmlclay.com/docs/guide/backups/).
- **`<file> changed since you last loaded it. Your version was not saved.`** (HTTP `412`, code `conflict`)
  The file on disk changed since your tab loaded or last saved it. Use the conflict bar on the page to choose **Keep mine**, **Accept theirs**, or **Download my copy** (see [Conditional saves and receipts](https://clayjs.com/docs/conditional-saves/)).
- **`body too large (max 50MB)`** (HTTP `413`)
  The HTML document being saved is larger than 50 MB. Upload large images and attachments through [uploads](https://htmlclay.com/docs/uploads/) instead of embedding them as `data:` URLs.
- **`empty body`**, **`body is not an HTML document`** (HTTP `400`), or **`/_/save takes the document as text, not JSON.`** (HTTP `415`)
  The request sent to `/_/save` was empty, not valid HTML, or sent with a JSON content type instead of plain HTML text.
- **`the file was just emptied on disk; retry once that change reaches the page`** (HTTP `409`)
  Another tool truncated the file on disk while your save was starting. Wait a moment for the disk change to settle and save again.
- **`invalid token`** (HTTP `401`)
  The document's save token is no longer valid, for example because you stopped trusting its folder. Reopen the file through HTML Clay.
- **`HTML Clay is restarting to finish an update, so nothing was saved. Try again in a few seconds.`** (HTTP `503`, code `restarting`)
  A save arrived while HTML Clay was restarting into a new version. Wait a few seconds and save again.
- **`File too large (max 25MB)`** (HTTP `413`, code `too-large`)
  An uploaded file is over the 25 MB per-file limit. Compress or resize the file before uploading.
- **`That kind of file cannot be uploaded`** (HTTP `415`, code `unsupported-type`)
  HTML Clay refuses uploads of HTML, XML, and JavaScript files (such as `.html`, `.htmlclay`, `.xml`, `.js`, and `.mjs`). Upload non-executable assets only.
- **`Expected one file part named "file"`** or **`Empty file`** (HTTP `400`)
  The upload request did not contain a `file` multipart field or the uploaded file was 0 bytes.
- **`<key> in <dir> is N bytes, want 32: delete it and upload again`**
  The secret file `~/htmlclay/uploads/.library-key` is damaged. Delete `~/htmlclay/uploads/.library-key` and retry the upload so HTML Clay generates a fresh 32-byte key.
- **`That file is no longer open.`** or **`Couldn't export <name>.`**
  When choosing **Export as Zip**, the document was closed after the menu opened, or HTML Clay could not write to `~/Downloads`. Reopen the document in HTML Clay and verify that `~/Downloads` exists and is writable.

## Updates

See [Updates](https://htmlclay.com/docs/guide/updates/).

- **`HTML Clay could not restart into vX just now, so it is still running vY. Try Restart to Update again in a moment.`**
  The update restart could not complete. Click **Restart to Update** in the tray menu again.
- **`The update to vX has not started yet, so HTML Clay is still running vY. It finishes the next time HTML Clay quits.`**
  On macOS, Sparkle did not finish quitting the app within 40 seconds. Quit HTML Clay normally when you are ready to complete the update.
- **`Self-update is off: <reason>`** (in `htmlclay.log` or from `htmlclay update-now`)
  Automatic updates are disabled because `"updates": "off"` is set in `config.json`, HTML Clay is running with `-no-tray`, the install folder is not writable, or on macOS the app is translocated outside `Applications`. Move `HTML Clay` to `Applications` on macOS, or click **Update available: vX.Y.Z** in the tray menu to download the new version manually.

## Live sync

See [Live sync between tabs](https://htmlclay.com/docs/live-sync/) and ClayJS [live sync](https://clayjs.com/docs/plugins/live-sync/).

- **Nothing updates in the open tab when the file changes on disk**
  Check that your document's ClayJS `<script>` tag loads `sync` (for example, `clay.js?plugins=sync`). Reload the tab after adding the plugin, and verify that the tab's address bar shows `http://<slug>.localhost:<port>/...` rather than `file://`.
- **Your words in the document were replaced by an outside change**
  The external edit and your unsaved edit modified the same text. Keep concurrent edits in separate elements, or restore your replaced text from the conflict notice that appears on the page.

## JSON over HTTP

See [JSON over HTTP](https://htmlclay.com/docs/json-http/) and ClayJS [data: pages as JSON](https://clayjs.com/docs/plugins/data/).

- **`400` (`Write rejected`) for an unknown key or unmatched selector**
  The JSON payload contains a key not defined in the extraction rules, or the rule's selector matched nothing in the document. Send only keys defined in the rules and verify the target elements exist.
- **`400` for the `data` parameter or rules tag**
  The `data` query parameter is empty, malformed, or repeated, or the embedded `<script data-rules-name="api">` tag does not have `data-rules-version="1"`. Also check that your selector uses only supported pseudo-classes and operators (for example, `["sel", {"name": "@name"}]` instead of `sel@name[]`).
- **`400` (`Write refused`)**
  The write targeted an unsafe or forbidden target, such as an `on*` event attribute, `style`, `srcdoc`, `@innerHTML`, `@outerHTML`, a `javascript:` or `data:` URL, an element inside `<script>` or `<head>`, or a region marker (`no-save`, `editor-ui`). Adjust your rules to target ordinary content elements and attributes.
- **`400` (`Cannot grow list`)**
  You sent new items for a list that is currently empty in the HTML and has no `cms-template` seed to clone. Keep at least one item in the list or add a template seed.
- **`405` on a `POST` to the file's own address**
  Include the `?data=` query parameter on the URL, or send the `POST` to `/_/api/<path>`.
- **`403` (`Not writable`) on a write**
  The target file is not currently open in HTML Clay and is not a `.htmlclay` file in a [trusted folder](https://htmlclay.com/docs/guide/trusted-folders/). Open the file in HTML Clay first. If sending the request from a browser script on the same origin, include the document's `Save-Token` header.
- **`404` (`No open folder`) on `127.0.0.1:<port>/_/api/<path>`**
  No open folder in HTML Clay serves that file path. Open the file in HTML Clay first, or run `htmlclay wire where <file>` to see its folder address.
- **`412` on a write with `If-Match`**
  The file on disk changed since you read its `ETag`. Read the file again, apply your change to the new data, and retry with the new `ETag`.
- **PowerShell `Invoke-RestMethod` fails with `remote name could not be resolved`**
  Windows system DNS does not always resolve `*.localhost` names for CLI tools. Send the request to `http://127.0.0.1:<port>/_/api/<home-relative-path>` instead.

## Document programs and the wire CLI

See [Document programs](https://htmlclay.com/docs/programs/) and [The wire CLI](https://htmlclay.com/docs/wire-cli/).

- **`open it first` or `has never served this file's folder` in the terminal**
  Open the document in HTML Clay at least once so its folder is registered, then run `htmlclay wire serve` again.
- **`no agent is attached to this file` on the page**
  If you attached a program from the terminal, check that `htmlclay wire serve` is still running. If you are using a named document program, check that `<meta name="htmlclay-helper" content="<name>">` appears in the first 512 KiB of `<head>` and matches the `helper` name in `clay.wire.send`.
- **`was not granted that helper` on the page**
  You declined the helper prompt, or you reached the document via a link rather than opening it directly. Double-click the `.htmlclay` file in your file manager to open it directly and choose **Allow for This Document** or **Allow for Any Document**.
- **The page stays on its loading state and never receives a JSON result**
  Stop `htmlclay wire serve` and restart it with `--protocol=jsonl`, then reload the page. Without `--protocol=jsonl`, HTML Clay treats standard output lines as plain progress text instead of JSON result records. Write diagnostic messages to standard error (`stderr`) and keep result records under 512 KiB.

## AI editing

See [AI editing](https://htmlclay.com/docs/guide/ai-editing/) and ClayJS [`ai-edit`](https://clayjs.com/docs/plugins/ai-edit/).

- **The bar says an agent was not found or is not signed in**
  Install Claude Code or Codex on your computer and sign in from your terminal, then send the request again. HTML Clay falls back between Claude Code and Codex only when the default CLI is missing; an explicit `@agent` prefix or a sign-in failure never falls back.
- **Unknown `@name` in the prompt**
  Remove the `@name` prefix to use your default agent, use `@fable` or `@codex`, or define the custom engine under `aiEdit.engines` in [`config.json`](https://htmlclay.com/docs/configuration/). (`@agy` is always refused because it can read files without asking.)
- **AI editing is turned off, with no Send button**
  Enable **AI Editing** in the HTML Clay tray menu.
- **Pressing `Cmd+J` (`Ctrl+J` on Windows and Linux) does nothing**
  Check that the document loads ClayJS with `?plugins=ai-edit`, is open through HTML Clay in edit mode, and that you have selected text inside a content element. If your browser captures the shortcut, click the **AI** chip next to your selection.
- **Another request is running**
  Each document runs one AI edit at a time. Wait for the current edit to finish, or click **Stop** in the bottom bar.
- **Reply refused for adding code, `reply is not a single` element, or `the model declined this request`**
  ClayJS refuses any reply that introduces `<script>`, inline event handlers, `javascript:` URLs, `srcdoc`, or new `<iframe>`, `<frame>`, `<object>`, or `<embed>` elements. Ask again without requesting executable code, or rephrase the request.
- **The selected element is too large**
  Select text inside a smaller element, such as a single paragraph or list item. Selecting fewer words inside the same large container still sends that whole container.
- **A request stops after five minutes**
  Each AI edit has a 5-minute time limit. When it expires, HTML Clay stops the agent and restores the original content.
- **Attachment (`@name.ext`) refused**
  Attached files must be regular, non-hidden files inside the document's folder (up to 8 files, at most 256 KiB each and 1 MiB total). Missing files, hidden files (such as `.env` or `.git`), and symlinks resolving outside the folder stop the request.
- **`HTML Clay stopped this edit.`**
  You unchecked **AI Editing** in the tray menu or quit HTML Clay while the request was running.
- **Clicking Keep reports a save error**
  The rewrite is visible on the page, but saving to disk failed or hit a conflict. Copy the rewritten text before reloading or closing the tab, then resolve the save error and save again.