Kico for WordPress: troubleshooting

Last updated: October 26, 2026

Kico for WordPress connects a self-hosted WordPress site to Kico. Most problems come from something between Kico and the site: a firewall, a security plugin, the host’s file permissions or a cache. Start with Check site on the site’s card in Kico (Account → Connectors). It asks the site what it runs, tries a harmless write, sends a request a firewall would typically block, and checks the live preview. Each result says what it found and what it means. Copy the results puts them on the clipboard for a support request.

The site does not connect

  • “did not accept the pairing (404)”: Kico reached the site, but the site did not answer on its REST API. Check that Kico for WordPress is active, that https://your-site/wp-json/ opens in a browser, and that no security plugin turns the REST API off for visitors. Click Connect to Kico in wp-admin again: a pairing request lasts 10 minutes.
  • “This connection request expired”: the 10 minutes passed, or the request was used already. Start again from wp-admin → Settings → Kico.
  • “Kico could not reach …”: the site’s address does not answer from the internet (a staging site behind a password, a site on a local network, a firewall that blocks data centers). Kico needs to reach the site over HTTPS.
  • The site was connected, now Kico says to connect it again: the key was removed in wp-admin (Settings → Kico → Disconnect), the plugin was deactivated, or the WordPress user Kico acts as is no longer an administrator. Connect it again from wp-admin; Kico keeps the history of the site and picks it up again.

A firewall blocks Kico’s requests

Kico sends SQL, PHP and file content to the site, which web application firewalls (ModSecurity with the OWASP rules, host firewalls, Cloudflare, Wordfence and similar plugins) often block. Check site reports it as “Firewall in front of the site”.

  • Update Kico for WordPress: newer versions wrap every request so that firewalls let it through.
  • Or allow requests to /wp-json/kico/v1/ in the firewall. Every one of them is signed with a key only Kico holds; the site answers nothing else on that path.
  • Large changes (uploads, big files) can hit body size limits of the server (post_max_size in PHP, client_max_body_size in nginx). Kico sends large bodies in parts when the plugin supports it.

Writes fail

  • Files: when PHP may not write to wp-content, plugins, themes or uploads (the files belong to another user than the one PHP runs as), Check site lists them. Agents then use other routes: the database, WP-CLI, or ask you to change it in the host’s panel. To let Kico change files, give the PHP user write access to those folders, or ask the host.
  • Disabled PHP functions: hosts often disable exec, proc_open and similar. WP-CLI through Kico needs proc_open; PHP through Kico does not.
  • DISALLOW_FILE_EDIT / DISALLOW_FILE_MODS: these switch off the file editor and plugin installs in wp-admin. Kico’s own tools write files directly and are not stopped by them; a connected Kico can change code on the site.
  • A change “may have run”: when the site stops answering in the middle of a write (a time limit, a crash), Kico asks the site afterwards what happened. If the site cannot say, Kico tells the agent the outcome is unknown, with the operation’s id; nothing is repeated by itself.

A change waits for approval

Writes you ask for in the chat run at once, and so do writes of a schedule you made. A write that an event or an incoming mail started waits for your approval in Kico, as with other connectors; on a site shared with your organization it waits for one of its approvers. To let a tool run without asking, allow it in Account → Connectors, or ask Kico in the chat.

The live preview stays empty or shows the site without styles

  • Sites that refuse to be framed (an X-Frame-Options or Content-Security-Policy: frame-ancestors header set by the host, a CDN or a security plugin) are shown through the project’s preview address instead. Check site says which applies.
  • An http:// site cannot be framed directly in Kico (which runs on https://): it is shown through the preview address.
  • A page cache can show an old page after a change. Purge the cache (the caching plugin’s button, or the host’s), then reload the preview.

The plugin is out of date

The site’s card shows when a newer Kico for WordPress is out. Update it in wp-admin → Plugins (or Dashboard → Updates), or download it from Kico and upload it in wp-admin → Plugins → Add New → Upload Plugin. Your connection and keys are kept.

Turning Kico off

  • In Kico: Disconnect on the site’s card. The site forgets Kico’s key; Kico keeps the history of the site read-only (snapshots for 30 days, the changes for a year) under Disconnected sites, where you can export or delete it.
  • In wp-admin: Settings → Kico → Disconnect.
  • Without wp-admin: add define( 'KICO_DISABLED', true ); to wp-config.php, or rename the plugin’s folder.

Still stuck? Write to hello@kico.dev with the results of Check site.