When something stops, that is usually intentional. WPAgently would rather hold a draft than silently save an unclear change to your website.
This page turns a message into a next step. You do not need to read everything. Find the symptom you see.
If you use Paid with the CLI and the connection does not work, start with this command:
wp-agent doctordoctor checks the website, your sign-in, the Editor, the licence, and available tools. With Free, skip this command. Repeat the read-only task in Getting started instead. If the external connection still fails, open WPAgently > Connect agent and run the external diagnosis there.
Part 1: the five silent failures
These are the most common cases that WPAgently makes visible before a draft becomes a problem.
1. The post is unformatted
What you see
The post appears as one large Classic block in the editor, or the response reports freeform_count greater than 0.
What it means
WordPress could not understand the content as individual blocks. A block can be a heading, paragraph, or image. The Classic block is the old fallback view. It is not the right state for new WPAgently content.
What to do
Ask the assistant to create a new post through wp-agent/create-post-from-markdown, or a landing page through wp-agent/upsert-pattern. Raw HTML and hand-written Gutenberg block code do not belong in this workflow.
If needed, simplify nested lists or unusual tables and run the draft again. Do not publish until freeform_count is back to 0.
2. The SEO change stops
What you see
set-seo-meta returns HTTP 409 and manual_only. The title, description, or focus keyword stays unchanged.
What it means
SEO details are not stored as regular text. Rank Math, Yoast, AIOSEO, and SEOPress each use their own area. set-seo-meta returns HTTP 409 with manual_only before any provider mutation because WPAgently cannot safely write this change for every supported plugin.
What to do
Change the SEO title, description, or focus keyword directly in the SEO plugin in WordPress. Then ask the assistant to check the result again with wp-agent/get-seo-meta.
Do not repeat set-seo-meta in the hope that it will write on a second try. Here, manual_only deliberately means WordPress changed nothing.
3. New content is not visible straight away
What you see
A new post has an old preview, the sitemap does not look current, or a new link does not work yet.
What it means
A cache is a temporary saved copy. A sitemap is the list of your pages for search engines. WordPress normally completes some follow-up work only when you save in the editor.
What to do
With wp-agent article and wp-agent landing, this follow-up work runs at the end. If you use individual tools directly, ask the assistant to call wp-agent/refresh-hooks after a change.
If you use a caching plugin or CDN, clear its cache too. Then check the page in a private browser window.
4. An image is rejected or missing
What you see
The image upload stops, the featured image is missing, or alt text was not set.
What it means
Alt text is the short image description for screen readers and search engines. WPAgently requires it so images are not published without a description.
Some image links are blocked for security. This includes local addresses such as localhost, private networks, or redirects to them. The protection stops an image link from secretly reaching protected parts of your hosting.
What to do
Use a public https image URL or a local image file. Always include a specific image description, for example “Person editing a WordPress draft on a laptop”.
If an image URL has no recognisable extension, such as .jpg, .png, or .webp, WordPress may not be able to determine its type. Use a direct image address with an extension or download the file locally.
If direct-upload verification fails after saving, the created attachment is preserved. The response contains HTTP 409, wpagent_direct_upload_recovery_required, recovery_required=true, and the attachment_id for manual inspection. Check the attachment in WordPress and do not blindly repeat the upload.
5. A post would be created twice
What you see
The workflow stops because it found an existing post with the same slug.
What it means
A slug is the final part of a web address, such as my-new-post. In the CLI pipelines, an explicit slug must already be in WordPress's stored form: lowercase letters, digits, underscores, or lowercase percent octets, with single hyphens as separators and up to 200 characters. The CLI also rejects 59 percent-encoded sequences that WordPress core normalizes while saving, including encoded spaces and punctuation. Stable percent-encoded UTF-8 sequences such as %e4%bd%a0%e5%a5%bd and repeated underscores remain allowed. Direct ability calls pass the slug through WordPress's sanitize_title(). You can also omit it and let WordPress generate it from the title. The slug prevents the same request from creating two identical posts by accident.
Multiple exact matches are ambiguous and abort before any mutation. WPAgently never simply chooses the first result.
What to do
Check in the WordPress dashboard which post is correct. Give a new test post a new slug. For now, update an existing post manually in the WordPress editor.
Part 2: special cases
An existing post did not visibly change
Many pages use a page builder such as Elementor, Bricks, Breakdance, Oxygen, or WPBakery. Such builders can store content outside the normal WordPress text field.
Ask the assistant to detect the builder first. Elementor has its own limited tools. For Bricks, Breakdance, Oxygen, and WPBakery, WPAgently deliberately stops writes when it cannot check the visible result safely.
Global Styles has not been initialized
What you see
wp-agent/get-global-styles, wp-agent/list-global-style-variations, wp-agent/get-global-style-variation, a Spectra One export, or a portable preflight with a create_only Global Styles mapping returns HTTP 409 with wpagent_gs_no_post.
What it means
The active theme has no saved user Global Styles record yet. These read, export, and preflight paths remain read-only. They do not create a WordPress record. Without a record, they cannot provide a state_hash for a safe write.
What to do
Open Global Styles in the WordPress Editor and save once. Then run wp-agent/get-global-styles again. Use the new state_hash as expected_hash for wp-agent/set-global-styles or wp-agent/apply-global-style-variation. For a portable Spectra One preflight, select the desired mapping again and run the preflight once more.
Forms, shop data, or custom fields
Forms, WooCommerce products, and ACF fields have extra rules. ACF is a plugin for custom fields. The normal Editor does not automatically receive access to especially sensitive areas, such as form submissions or order data.
That is intentional. Enable only the one permission group you actually need. For orders, payment data, or form responses, you are usually better off working directly in the relevant WordPress plugin.
Your assistant cannot see tools
First check that Companion is active and that you selected the right profile in the WPAgently control center. Then open WPAgently > Connect agent, choose your assistant, and follow its instruction again exactly. With the Paid CLI, also run wp-agent doctor.
If your assistant still does not show wp-agent- tools, restart it. If WordPress offered a connection file for your assistant, import that exact file again. It contains its own Application Password. Treat it like a password and do not share it. With browser approval, repeat only the displayed steps instead.
What to include in a support request
Do not send credentials, licence keys, or a full database export. Instead, these details are useful:
- the exact error message
- your WordPress and PHP versions
- the assistant you used
- the task you wanted to run
- a screenshot of the affected WordPress page
That is usually enough to find the cause without sharing confidential data.