Docs & troubleshooting

Why it happens

The sending site's server didn't get a proper answer from the other site. Common causes: a wrong address, the site being in maintenance mode or behind a password or IP restriction, an SSL problem, or a firewall / security plugin / host bot-protection blocking the request. The longer message that mentions an "unexpected empty response" or a firewall means the same thing.

What to do

1. Check the Site URL exactly — https:// or http://, with or without www, no extra path.
2. In a browser, open https://the-other-site.com/wp-json/postdeploy/v1/status. You should get a short JSON response (usually an authentication error — that's fine, it proves the plugin is reachable). A login page, a firewall block page, or a 404 means the request isn't reaching PostDeploy.
3. Allow requests to /wp-json/postdeploy/ in your firewall, security plugin, or host protection, and remove any password or IP restriction from the receiving site.

Pushed several languages of the same page at once and only one of them failed this way, not all? That still points to a firewall or security plugin (Wordfence and similar are common) — it doesn't rule it out. These commonly give extra scrutiny to the very first request they've seen from a source in a while and wave through the next ones moments later, so a bulk multi-language push often shows exactly this pattern: the first language in the batch fails, the rest succeed. Re-pushing the failed one on its own usually works once the destination's already "seen" the connection — but the fix is to allow-list the PostDeploy route or the sending site so it doesn't happen again, not to leave the security plugin off.

Why it happens

The API key is wrong or out of date, it was copied from the wrong site, or the two servers' clocks are more than 5 minutes apart (each request is time-stamped and signed).

What to do

1. On the other site, open PostDeploy → Connections and copy This Site's API Key again. It must come from the site you're connecting to, not the one you're on.
2. Paste it with no leading or trailing spaces or line breaks and reconnect.
3. If it still fails, check that both servers show the correct time — ask your host to sync the server clock.

What to do

Install and activate PostDeploy (Free or Pro) on the other site, then update both sites to the latest release and try again.

Why it happens

PostDeploy limits how fast one connection can send requests, to protect the receiving site.

What to do

Wait a few minutes and try again. For many posts, use bulk or scheduled deployment (Pro), which queues them instead of sending everything at once.

Why it happens

Pro already includes everything Free does, and running both would show two PostDeploy menus and two connection lists. Pro won't run while Free is active.

What to do

Deactivate and delete the free PostDeploy plugin, then activate Pro. Pro keeps its own connections, so add them again after switching. Other sites can still run Free — a Pro site and a Free site push to and from each other normally.

Why it happens

Pro's conflict detection noticed that the page on the receiving site was edited after PostDeploy last wrote it. It stops so you don't lose those edits by accident.

What to do

Compare the two versions. If the receiving site's changes can be discarded, confirm the prompt to force the deployment; otherwise copy those edits back to the source first. Pro takes a snapshot before overwriting, so you can undo it — see Undoing a push.

What to do

The same post is already being deployed — usually a double-click, or a scheduled run overlapping a manual one. Wait for it to finish (check Deployments) and try again if needed.

Why it happens

PostDeploy migrates posts, pages, and custom post types that are public, have an admin screen, and support a title and editor. Internal types — media attachments and some page-builder storage types — are excluded on purpose.

What to do

Check the post type is registered the same way on both sites (same plugin active on each). If it holds internal data rather than content, it isn't meant to be migrated.

Why it happens

The content and data for one post can be at most 20 MB. Image and media files aren't counted (they're downloaded separately), so this is almost always huge inline data — for example images embedded directly in the text, or an enormous page-builder layout.

What to do

Upload embedded images to the media library and link to them, or split a very large page into smaller ones.

Why it happens

Elementor falls back to a single text block when it can't read a page's design data. That happens when the receiving site is running a version that can't read what was sent, or when the receiving Pro site's license isn't active.

What to do

1. Update PostDeploy on both sites to the latest release (Pro 0.9.60 or newer; the free plugin 0.9.64 or newer).
2. Make sure Elementor is active on the receiving site and, if it runs Pro, that its license is active.
3. Push the page again — it updates the existing page.

Why it happens

"Hide Title" is one of Elementor's page settings. Older versions didn't carry page settings across; they do from Pro 0.9.60. It can also come from the page template or a Theme Builder layout.

What to do

1. Update both sites and push the page again.
2. In Elementor, open the page's Settings (gear icon) on both sites and compare Hide Title and Page Layout.
3. If the source gets its layout from an Elementor Theme Builder template, recreate that template on the receiving site.

Why it happens

The page's template name is carried across, but the template itself isn't. Elementor's own templates (Full Width, Canvas) work anywhere Elementor is active. A template that belongs to your theme only works if the same file exists in the receiving site's active theme — otherwise WordPress quietly uses the default template.

What to do

Use the same theme (or child theme) on both sites, or pick a template that exists on the receiving site. In Elementor: Settings (gear) → Page Layout; in the block editor: the Template field in the sidebar.

Why it happens

A Loop Grid is different from every other widget on a page. Ordinary widgets have their content stored right inside the page — text, images, links all travel with it. A Loop Grid instead stores a query ("show me posts from this category," or "show me this custom post type") and runs that query live, against whichever site is currently rendering the page. Two things it depends on don't travel with the page at all:

• The grid's own Loop Item template — the design used for each item — is a separate Elementor Theme Builder item, not part of the page. It's stored as its own post, and the grid widget just references its ID — so if that ID doesn't exist (or means something else) on the receiving site, Elementor can show the grid empty, or — in some setups — hit a fatal error (Call to undefined method ...::print_content()) trying to render or edit the page at all.
• If the grid queries dynamically (by post type or category, the common setup) rather than showing specific hand-picked posts, the posts it's looking for also have to actually exist on the receiving site — otherwise the query correctly finds nothing there.

What to do

PostDeploy Pro 0.9.77+: pushing a page with a Loop Grid now offers to bring its Loop Item template along automatically, right in the push confirmation popup (checked by default) — accept it and the reference resolves correctly on its own, no manual export/import needed.

On an older Pro version, or on Free (which doesn't resolve Elementor references at all):

1. In Elementor on the source site, open the Loop Item template and use Export Template (saves a .json file). On the receiving site, go to Templates → Saved Templates → Import Templates and import it. This is Elementor's own tool for moving Theme Builder templates between sites — several related templates can be moved together with a Template Kit instead, if you have Elementor Pro.
2. If the grid queries a post type or category, push those underlying posts to the receiving site too (individually, or with Bulk Deployment for a lot of them at once) so there's something on that site for the query to find.

Why it happens

PostDeploy delivers the widget's code unchanged. The damage happens afterwards, when the page is saved in Elementor's editor on a site that has DISALLOW_UNFILTERED_HTML turned on (common on locked-down hosts and multisite). Elementor then strips the <script> tags and encodes the rest of the code, which can also delete part of it.

What to do

1. On the receiving site, ask your host or developer whether DISALLOW_UNFILTERED_HTML is set in wp-config.php, and remove it (on multisite, use a Super Admin).
2. Push the page again to restore the original code from the source, and avoid saving that page in Elementor until the setting is off.
3. If the setting has to stay, keep the JavaScript out of HTML widgets — put it in a code-snippet plugin or your theme instead.

Why it happens

PostDeploy copies files that are in the source site's media library (its uploads folder) and points the page at the copies. It can't copy images that live elsewhere: files uploaded by FTP outside the uploads folder, images from your theme, or images hosted on other domains. Web addresses that JavaScript builds while the page runs also can't be detected.

What to do

• Add the missing images to the media library on the source site, then push again.
• Update both sites to the latest release — images inside tabs and slides, inside HTML blocks, and addresses with no domain (like /wp-content/uploads/…) are handled from Pro 0.9.57.

Why it happens

The receiving site fetches each image directly from the sending site. If the sending site blocks direct file requests — hotlink protection, HTTP authentication, an IP allow-list, or bot protection on the uploads folder — the push stops and nothing is half-imported.

What to do

Allow the receiving site's server to fetch /wp-content/uploads/ on the sending site: switch off hotlink protection, remove the password, or allow that server's IP. Then push again.

Why it happens

The free plugin migrates JPG, PNG, GIF, WebP, and PDF files. PostDeploy Pro also handles SVG, BMP, TIFF, and ICO images, fonts (WOFF, WOFF2, TTF, OTF, EOT), and video (MP4, M4V, WebM, MOV). SVG files are cleaned of scripts on the way in.

What to do

Use Pro for those file types on the receiving site, or remove the file from the post.

What to do

The receiving site's PHP limits (upload_max_filesize and post_max_size) are smaller than the file. Raise them in your host's control panel or php.ini — or ask your host — then push again.

Why it happens

WordPress's built-in scheduler only runs when someone visits the site. On a quiet site, or one with caching that hides visits, a scheduled job can wait a long time.

What to do

1. Check the Queue page — it shows each item's status and any error.
2. Set up a real server cron so WordPress checks regularly. In wp-config.php:

   define( 'DISABLE_WP_CRON', true );

   and add a cron job on your server, every 5 minutes:

   */5 * * * * curl -s https://your-site.com/wp-cron.php?doing_wp_cron > /dev/null 2>&1

How it works

• You pick a destination in the PostDeploy: Auto-Push box on the post editor screen. The default is "Don't auto-push".
• It fires once, when the post changes to Published — including a normal WordPress scheduled publish. Later edits to an already-published post don't push again; use Push for that.
• It follows the same queue as scheduled deployments, so the same cron note above applies.
• Setting up a new auto-push needs an active Pro license; one you already set up keeps working if the license later lapses.

Why it happens

Either activation wasn't completed, or the license has expired. Without an active license, ACF / Elementor / WPML resolution, new snapshots, new bulk and scheduled deployments, setting up auto-push, and WP-CLI are unavailable.

What to do

1. Open PostDeploy Pro → License, paste your key, and click Activate License.
2. If the message says a confirmation email was sent, click the link in that email, then reload the License page.
3. If the license expired, renew it in the customer portal.

Nothing you already created is lost while a license is inactive: existing snapshots stay restorable, deployments already queued still run, and Posts, Pages, custom post types, and your connections keep working.

In the customer portal. You can also manage your subscription and download invoices there.

Each plan covers a set number of sites — 1, 3, 10, or unlimited. Activate the same key on each site, up to your plan's limit. To free up a slot, deactivate the license on a site you no longer use. Staging environments may not count against this limit at all — see the next question.

Why it happens

Licensing recognizes common staging/development URL patterns automatically — a hostname that contains localhost or 127.0.0.1, starts with local., dev., test., stage., or staging., or ends with .dev, .test, .staging, .local, .example, or .invalid. For example, staging.yoursite.com matches; a name like yoursite-staging.com does not, and counts as an ordinary site.

Whether a matched staging/dev site is free is a setting on the license itself. When it's enabled, activating on a matching URL doesn't use up a site slot at all, on any plan. When it isn't, a staging URL counts the same as a production one.

What to do

Check your account in the customer portal to confirm whether free staging activation is enabled for your license. Either way, naming your staging environment with one of the patterns above (a staging. subdomain is the simplest) is what makes it eligible.

Why it happens

Copying an entire WordPress install (files and database) with a backup/migration plugin carries PostDeploy Pro's license data and connections along with everything else, so both the original and the copy can end up looking identical.

What happens to the license

Licensing detects this automatically and pauses ("safe mode") until you tell it which of these is true, from an admin notice: the copy is a duplicate for staging or testing (keeps working, doesn't use a site slot), this is the new home of the original — a real migration, so the license moves with it and the old URL retires — or it's a genuinely new, separate website, which needs its own license activation and does use a site slot.

What happens to your connections

PostDeploy's own site-to-site connections are separate from licensing. If the migration copies everything (including wp-config.php), the copy comes out as an exact working duplicate — same identity, same connections, same stored keys — which also means it can immediately push or pull to every site the original was connected to. If you meant the copy to be a disposable staging site, open Connections on it, remove or repoint anything that shouldn't have live access to production, and click Regenerate Key to give the copy its own identity. If instead the destination got fresh wp-config.php secrets (common when a host provisions a brand-new install), connections will still be listed but won't authenticate until you re-add them — nothing sends silently in that case.