Troubleshooting · HTML Clay docs

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

Opening files, addresses, and trusted folders#

See Opening files and addresses and 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, Uploads and assets, and Export as zip.

<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.
<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).
body too large (max 50MB) (HTTP 413) The HTML document being saved is larger than 50 MB. Upload large images and attachments through 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.

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 and ClayJS 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 and ClayJS data: pages as JSON.

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. 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 and The 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 and ClayJS 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. (@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.