Skip to main content

Troubleshooting

etch_list_targets is empty​

The server is running but no builder tab is connected to the local connector.

  1. Confirm the Etch builder tab is open in an authenticated WordPress admin session.
  2. Enable AI Connector in Etch if the builder asks for it, then click AI Connector again - the tab dials out to 127.0.0.1:7331 only when connected.
  3. Call etch_list_targets again (or etch_recall_project_memory, which falls back to listing when no working target exists).
  4. If your harness runs in client mode (reusing an existing connector), confirm at least one other harness is actually running and hosting the connector. A client with no host has nothing to connect through.

Never share your WordPress credentials with the agent - the authenticated browser tab is the only credential involved.

Could not bind the connector WebSocket port 7331​

Another process owns port 7331 and is not acting as the shared connector - often a foreign process, or an older 1.1.x etch-agent that predates connector sharing. Either free port 7331, or give this instance its own port:

"args": ["SERVER_PATH", "--client-name", "claude", "--connector-ws-port", "17331"]

A custom port runs standalone: it does not host the shared control server and does not reuse another connector.

bun install fails on the packaged runtime​

  • Bun too old. bun --version must report 1.3.14 or newer; older releases are not verified against the packaged lockfile.
  • Frozen lockfile mismatch. Run the exact form bun install --cwd mcp --frozen-lockfile --no-save from the package root. The lockfile pins exact versions with integrity hashes; any drift is a hard error by design.
  • Upgrading the package. Unzip the new release over the existing etch-agent/ folder (the folder name is version-agnostic) and re-run the install command.

ACSS detection returns a safe-mode error​

etch_detect_acss reads the builder tab's stylesheets, and the Connector's safe-mode sandbox withholds page access entirely:

"globalThis" is not available in safe mode — only "etch" and standard JS
built-ins are exposed. Connect the tooling in unsafe mode to run arbitrary scripts.

To use detection, connect AI tooling in unsafe mode in the Etch builder. Detection is optional for everything else: all editing tools work in safe mode, and the agent can follow the bundled acss skill once ACSS is confirmed manually.

Switching posts or templates is refused​

etch_open_post and etch_open_template refuse while the document has buffered (unsaved) changes. Save with etch_save_document, or discard with etch_undo repeated until clean - etch_get_status reports the unsaved-changes state.

Edits appear in the builder but WordPress is unchanged​

That is the buffered editing model working as designed. Block, style, and loop edits land in the open document only; nothing reaches the database until an explicit, user-approved etch_save_document. Note the exceptions that persist immediately: global stylesheets, components, custom fields, and Project Memory.

A staging site moved to production (or the domain changed)​

Project Memory is keyed by the normalized site URL; it never merges data across URLs automatically. The agent runs etch_recover_project_memory in preview mode, confirms the target URL has no memory and both URLs are the same project, then applies the rebind. If the local store is corrupt, the same tool quarantines it to a sidecar file so a fresh store can be created.

Two agents on the same target​

Only one agent should mutate the same Etch target at a time - two agents editing one builder tab will collide. Keep one mutating agent per target; reading, and any work on other targets, is fine in parallel. Multiple harnesses (Claude Code, Codex, opencode, …) can all run simultaneously and share one connector.

The agent improvised a block structure that broke​

The agent should read the bundled etchapi skill (mcp/skills/core/etchapi/SKILL.md) before editing on a site - it defines the safe block shapes and the read-then-write flow. Recovery from a bad apply is always etch_undo, repeated as needed, before any save.