Where uploaded files go during a migration

A GravityMigrate file carries your forms, entries and settings, but by default it does not carry the files people uploaded through those forms. It records where each file lives on the old site, and the new site downloads them from there while it imports. This article explains what that means, why a download can fail, and how to make sure your files come across.

How files travel #

When you export with Uploads & Files selected, the migration file stores the address of every uploaded file on the old site. During the import, the new site fetches each file from that address, saves it into its own uploads folder, and points the entry at the new copy. For that to work, three things have to be true at the moment of the import:

• The old site is still online.
• The new site’s server can reach it. A login, a password, an IP allowlist, or a firewall that blocks unfamiliar requests all make a site unreachable in that sense, even when you can open it in your browser. A site that only exists on a private network or a local computer is unreachable too. The address itself also has to be public, because the import refuses to fetch from a private or local one.
• The files are still there, at the same addresses.

The export screen says as much next to the option: “Your files stay on this site, and the other site fetches each one from here while it imports.”

When a download fails #

If the new site cannot fetch a file, the import carries on and the entry keeps pointing at the old site. The form, the entry and its other answers arrive as normal. Only the file link still leads to the old address, and it stops working once that site is taken down.

Before an import starts, GravityMigrate checks whether it can reach the old site at all. When it cannot, the import screen says so: “Please Note: The export site is not accessible remotely to be able to import Uploads & Files.” A single file that fails during the import is recorded in the migration log rather than on screen. On the command line, the import ends with a count of the files that did not download. Four situations cause this:

• The old site is protected. A staging site behind a password, a site that only logged-in people can see, or a host that only accepts requests from known addresses.
• A firewall blocks the requests. Cloudflare, ModSecurity, Wordfence and similar tools can treat the new site’s downloads as an attack. Firewall or WAF blocking GravityKit imports and exports lists what to allow for each of them.
• The old site redirects. A domain that now forwards elsewhere, or an address that answers with a login page instead of the file, hands the import a web page rather than an image or a document, and the import refuses it.
• The old site is already gone. Once it is switched off, there is nothing left to fetch from.

Making sure the files come across #

• Keep the old site online and reachable until the import has finished. Export, import, check a few entries with files, and only then take the old site down.
• When the old site’s stored address is not reachable from the new server, export from the command line instead, and give the export a public address to use. The --public-url flag of wp gk migrate export rewrites the file addresses inside the migration file, and Migrating Gravity Forms from the command line with WP-CLI covers it.
• When the old site is already gone, the files can still be moved by hand if you have a copy of its wp-content/uploads folder. Copy the gravity_forms directory inside it to the same place in the new site’s uploads folder, then replace the old site’s address with the new one in the entries with a search-and-replace tool. WP-CLI’s wp search-replace does that across the Gravity Forms tables when run with --all-tables. Take a backup first.

Packaging the files inside the migration file #

The export step has an option, Include the files, so the download stands on its own, that writes the files themselves into the migration file. Tick it whenever the old site might be offline, unreachable or gone by the time somebody imports, and especially when you are about to shut it down. The file gets larger, and the screen tells you how much can fit inside it. That limit follows the old site’s own upload size limit. Files beyond it stay on the old site and are downloaded during the import as before, and the export’s Done step says how many stayed behind. On the command line, --include-files on wp gk migrate export does the same.

Files that add-ons create #

The files that travel, packaged or fetched, are the ones uploaded through File Upload and Post Image fields, the images a Gravity Forms Signature Add-On field draws, and the images an Image Choice field offers. Files that other add-ons generate and store on their own, such as the documents Fillable PDFs produces, are not part of the migration and stay on the old site. Copying those folders by hand, as above, is the way to move them.

Related articles #

• Getting started with GravityMigrate
• Migrating Gravity Forms from the command line with WP-CLI
• Firewall or WAF blocking GravityKit imports and exports