Export and import your Media Library

In short. Media Library export packages every original file you've uploaded — images, videos, PDFs — into a single ZIP archive. Import reads that ZIP back in and recreates the files at the same paths, so pages and posts that reference them keep rendering without broken links. The controls don't appear in the SGEN 3.0 left nav — your platform team runs them through server-side admin tools. To get started, send platform a one-line request: operation, source site, and selection mode (All or Files only). That's the full picture — details below.

On this page: What this is for · Scope table · Examples · Before you start · Steps · Troubleshooting

How to back up and restore your media library between SGEN sites

What is this for?

Media export packages every original uploaded file in your uploads/ directory into a ZIP archive. The archive contains originals only — SGEN excludes any subdirectory matching a known size-variant key (thumbnails, retina sizes, srcset crops), because those regenerate on first request after import. When you choose the All selection, the archive also includes a database/media.json metadata file recording each file's title, alt text, description, and original public URL.

Media import reads a ZIP — either one produced by SGEN's own export, or a migration ZIP from another SGEN site — and loads its files into the current site's uploads/ directory. If the ZIP includes media.json, the importer recreates filenames, titles, and descriptions exactly as they were on the source site. Without media.json, the importer walks the ZIP tree and uploads every file it finds, generating fresh metadata on the way in.

Built for three jobs:

• Disaster recovery — a snapshot to restore after a bad migration, an accidental bulk delete, or a tenant rebuild.
• Site cloning — move every asset from staging to production once content is finalized.
• Agency handoff — give an external team the full asset library as a single archive so they can spin up a parallel SGEN site.

After a clean import, files land at the same relative paths under uploads/ as the originals. Pages, posts, and SG-Builder components that reference those paths resolve correctly without any URL rewriting. Thumbnail variants regenerate the first time a public page requests a size. The Media Library grid shows imported rows as soon as the import completes.

Scope

Media export and import cover originals plus optional metadata. They don't touch any other content type.

Good use cases

Use this table to match your scenario to the right operation and flags. The selection mode and overwrite preference are the two decisions that change per job — everything else in the process is the same.

Selection quick rule: use All any time the ZIP will be imported on another SGEN site — it preserves titles, alt text, and descriptions so the destination Media Library looks exactly like the source. Use Files only when you only need the raw files and metadata is safe in your live database (for example, a quick backup before a risky bulk delete).

Examples

Pre-launch backup. Two days from launch, a platform lead exports the staging media library with the All selection — originals plus media.json. The ZIP goes to secure cloud storage. If anything breaks during DNS cutover, the backup is there to restore from.

Staging-to-production clone. After content finalization on staging, the platform team exports with All, then imports into the production site with overwrite on — guaranteeing the destination matches the source byte-for-byte. Because the import uses media.json to match filenames and metadata, every image lands at the same path it had on staging, and SG-Builder pages copied across resolve images on first render. This is the canonical go-live pattern: export staging → import production → capture a fresh baseline export on production.

Disaster recovery. A bulk delete removes 80 files; a 30-day trash purge means some are gone from the active site. Platform imports a six-day-old ZIP with overwrite off — the importer skips files that still exist and only restores the deleted ones. The library is back to pre-incident state in under five minutes. This is the strongest argument for scheduled exports: your last export is your DR snapshot.

What NOT to use this for

• Don't use it for a single-file download. To retrieve one file, copy its public URL from the Media Library grid (right-click the thumbnail → Copy image address). The export ZIP packages the entire library — not practical for one file.
• Don't import on a live ecommerce store during peak hours. Imports write files synchronously and can lock the uploads directory for several minutes on large archives. Schedule imports for off-peak windows or a maintenance slot.
• Don't import a ZIP from a non-SGEN source without inspecting the structure. The importer expects either a database/media.json plus a flat file tree, or a uploads/-style folder structure. A ZIP from a different CMS or a local archive may have a layout the importer doesn't recognize — results will be unpredictable.
• Don't rely on it as your only backup. The ZIP covers media files only. A complete site backup also needs pages, posts, products, theme settings, custom codes, and the database. Media exports supplement the platform team's server-side backup pipeline — they don't replace it.
• Don't run two exports in parallel from the same admin session. The export builds a temporary file on the server before streaming it. Two parallel runs can fight for the same temp path, causing one to fail with a misleading error. Run them sequentially.
• Don't import into a tenant being actively edited. If a teammate uploads a file at the same moment an import is writing files, database row counts can desynchronize and the Media Library grid may show ghost rows. Coordinate imports as a maintenance window.

How this connects to other features

• Pages and SG-Builder pages — image references inside SG-Builder components store the Media Library's public URL. Re-importing media at the same paths means SG-Builder pages copied across will render images on first request with no URL rewriting. Migrate pages without media (or vice versa) and you'll get placeholder boxes — neither half of the migration is complete on its own.
• Ecommerce products — every product row stores its image as a Media Library reference. A migration that recreates media at the same paths restores all product images automatically. The product import in Ecommerce → Tools does not bring images — images come through this media import path.
• Blog posts — the blog post export captures post text and metadata; this media import restores the images those posts reference.
• Custom Codes — if your Custom Codes contain hardcoded absolute URLs to Media Library assets (for example, a logo URL on a tracking pixel), those references still point at the source domain after a clone. Verify Custom Codes after a migration by spot-checking the public-source HTML.
• GCP Cloud Sync — exports include local filesystem files only. Cloud-synced files are referenced by URL on the public site but their canonical location is GCS — those files travel through the GCS console, not this export. Coordinate with platform if you're migrating a site using GCP Cloud Sync.

Production migration order: export pages → export media → export products → export site settings. Import in the same order on the target. Verify each step on a public page before moving to the next.

Before you start

• You're signed in as an SGEN admin, and your platform team has access to launch the export and import operations (the controls don't sit in the standard left nav on SGEN 3.0 — they're reached through server-side admin tools).
• For an export: your uploads/ directory contains at least one eligible file. Exporting an empty library returns "Nothing to export: no eligible files found."
• For an import: the ZIP is ready and within the platform team's size limit. Larger archives need to be split or moved by direct filesystem transfer.
• For a migration: you have a maintenance window agreed with your team. Large imports can lock the uploads directory for several minutes; running them during peak traffic risks broken-image renders for live visitors.
• You have a way to verify the result on the public site — an incognito window, so you're not seeing a cached version.
• You know which selection you want: All includes media.json (recommended for migrations); Files only skips it (smaller archive, faster import on a fresh tenant).
• For an import: you've decided whether to enable overwrite. Leave it off for disaster recovery (restore only missing files); turn it on for a clean staging-to-production clone.

Where to go

The export and import controls don't have a sidebar entry on SGEN 3.0. Your platform team reaches them through server-side admin tools. If you have an old bookmark for Media Library → Import/Export, it returns a "page not found" screen on 3.0 — the UI tab was retired, but the operations remain available to platform.

When you raise a request, give platform three things in writing:

1. The operation — export, import, or export-then-import for a migration.
2. The source site and destination site (for migrations) or only the source site (for backups).
3. Any flags — selection mode (All or Files only) and overwrite preference (on or off).

A clear request shaped like: "Run a full export with media.json on staging.yourdomain.com, then import it into yourdomain.com with overwrite on, during the Tuesday maintenance window." lets platform run the operation without back-and-forth.

Steps

The six steps below cover the full export-then-import cycle. If you only need an export (for a local backup, not a migration), complete steps 1 and 2, then stop. If you're only importing a ZIP your platform team already has, start at step 4.

Tip on timing: for large libraries (hundreds of MB), coordinate with platform on a maintenance window before step 4. Imports can lock the uploads directory for several minutes and may cause broken-image renders on any page that requests a media file mid-write.

1. Request the export from your platform team

Send platform a request naming the source site, the selection mode, and where to put the resulting ZIP. Use the All selection if the export will feed a future import on another SGEN site (it preserves titles, alt text, and descriptions); use Files only for a leaner archive for offline storage.

A request that works in one round-trip:

Hi platform team — please run a media export on staging.yourdomain.com.Selection: All (include media.json)Output: drop the ZIP in our shared backups folderReason: pre-launch baseline before Friday's DNS cutover

Platform launches the export and your browser receives a file named media_export_<YYYY-MM-DD_HHMMSS>.zip — the timestamp is generated by SGEN at the moment of export, so two exports won't collide on filename.

If the source library is empty, the export reports "Nothing to export: no eligible files found." Confirm at least one original file exists in Media Library → All Files before re-running.

2. Verify the archive on disk

Open the ZIP locally with any unarchiver (Finder, Windows Explorer, 7-Zip). You should see a uploads/ folder containing every original file at its expected path, plus a database/media.json file at the root if you ran with the All selection. Spot-check a handful of filenames against your live Media Library to confirm the export was complete.

A typical archive listing:

Archive: media_export_2026-04-23_143022.zip Length Date Time Name --------- --------- ----- ---- 412345 2026-04-21 09:14 uploads/2026/04/yourstore-canvas-tote-hero.jpg 387856 2026-04-21 09:18 uploads/2026/04/classic-tshirt-front.jpg 521430 2026-04-19 14:27 uploads/2026/04/digital-guide-2026-cover.png 294128 2026-04-18 16:02 uploads/2026/04/sticker-pack-grid.jpg 18451200 2026-04-17 11:38 uploads/2026/04/store-tour-2026.mp4 627042 2026-04-15 10:09 uploads/2026/04/wholesale-pricing-2026.pdf 14782 2026-04-23 14:30 database/media.json --------- ------- 327548921 215 files

If the archive is much smaller than expected, your library may contain non-original variants (resized thumbs) that the exporter correctly excluded — that's normal. If it's wrong by an order of magnitude, re-run the export and ask platform to capture the server logs alongside.

3. Move the archive to the destination

Get the ZIP onto the destination site's filesystem or into a place where the destination admin can hand it back to platform for import. For a same-team migration, a secure cloud-storage handoff (Drive, S3 signed URL, encrypted file share) is typical. For an agency handoff, agree on a transfer mechanism that meets your security policy.

4. Request the import on the destination

Send platform a second request naming the destination site, the ZIP filename, and the overwrite preference. Use overwrite on for a clean clone (staging to production, fresh tenant); use overwrite off for disaster recovery (restore missing files, don't touch anything else).

A request that works:

Hi platform team — please run a media import on yourdomain.com.ZIP: media_export_2026-04-23_143022.zip (327 MB)Overwrite: ON (clean clone from staging)Window: Tuesday 9pm – 10pm Pacific (maintenance)

A successful import produces a summary platform can paste back to you:

Result: successFiles imported: 214Files skipped: 0Metadata updated: 214Errors: (none)media.json applied: yes

The media.json applied: yes flag confirms that the importer found and applied the metadata index — full metadata recovery. no means it walked the ZIP tree and generated fresh rows.

5. Verify on the destination site

Open the destination site's Media Library grid and confirm imported rows appear with correct titles, sizes, and thumbnails. Then open a public page that referenced one of the imported files and confirm the image loads. A right-click → View page source on a known image reference is the fastest check — the image's src should resolve to the same path it had on the source site.

Quick spot-check:

1. Open a representative page in an incognito window.
2. Right-click the hero image → Copy image address.
3. Paste into a fresh tab — the image should load cleanly.
4. Confirm the src matches the source path (same year/month subfolder).

If the destination site uses a CDN, issue a cache purge for the affected paths before external visitors see the imported images.

6. Capture a baseline export on the destination

Once the import is verified, request a fresh export on the destination site. This captures the post-migration state as a baseline backup before any new uploads happen.

media_export_2026-04-23_143022.zip <- pre-migration source exportmedia_baseline_post-migration_2026-04-23_152011.zip <- post-migration baseline

Keep both. Storage is cheap; reconstructing missing files from memory is not.

What success looks like

After a successful export and import cycle:

• The export ZIP downloads with a filename matching media_export_YYYY-MM-DD_HHMMSS.zip.
• Unzipping reveals a uploads/ folder mirroring the source site's directory structure, plus database/media.json (when you ran with All).
• The import summary reports success with non-zero Files imported and an empty Errors list.
• The destination site's Media Library grid shows every imported file with correct titles, sizes, alt text, and descriptions.
• Public pages that referenced the migrated files render images on first load — no broken-image placeholders.
• An immediate post-migration export captures the destination state as a baseline backup.

What to do if it does not work

Most issues fall into three categories: the ZIP didn't produce what you expected (empty or wrong size), the import wrote files but something is off in the grid or on the public site, or the operation completed but with a non-empty errors list. Read the errors list first — each entry names the specific file and the reason, which narrows the diagnosis quickly.

• "Nothing to export." Your uploads/ directory is empty or contains only size-variant subdirectories the exporter excludes. Confirm at least one original file exists in the Media Library grid. If the grid is empty but you expected files, escalate to platform to check filesystem state and any recent cleanup jobs.

• "No ZIP file uploaded." The upload arrived without a file attached. Re-run with the ZIP attached to the upload field labeled file.

• "0 imported and 0 skipped." The ZIP extracted but no eligible files were found. Most common causes: a non-SGEN ZIP layout, all files in subdirectories named index.html or database/ (both skipped by design), or a corrupted ZIP. Open the ZIP locally, verify its structure, and re-import.

• "Success but the errors list is non-empty." Read each entry — it names the specific file and the reason it was skipped (typical: zero-byte file, rejected filename characters, refused path traversal). Files in the errors list were not written. Reconcile with the source library and re-import only the missing files if needed.

• "Pages render with broken images after import." The files were imported but their paths don't match the source. Open the affected page's view-source and find the image URL, then check whether that exact path exists in the destination Media Library. A year/month subfolder mismatch (source and destination created in different months) is the usual cause. Options: re-import with overwrite on to force source paths, or update the page's image references to point at the new paths.

• "Missing-file errors for thumbnails and srcset crops." Variant sizes regenerate on first request after import — the first page load after a migration is the slowest. If missing-file errors persist after several reloads, the variant generator may not have write permission on the destination's uploads directory. Escalate to platform.

• "Duplicate rows in the Media Library grid." This usually means the importer ran with overwrite off against a destination that already had rows for some imported files, and metadata reconciliation added both old and new rows. Check the affected rows by upload date — duplicates will be the older ones. Trash the older entries from the grid. To prevent recurrence, run imports against a clean destination or run with overwrite on.

• "The export started but the browser timed out." Very large libraries can exceed the browser's default request timeout. Platform's tooling has no equivalent timeout and is the right path for big libraries. If even that times out, ask platform to split the uploads directory and run the export on each chunk separately.

• "After import, Custom Codes references broke." A media import preserves file paths, but Custom Codes that contained absolute URLs with the source domain (for example, https://staging.yourdomain.com/sites/..) still point at staging after a clone. Find the Custom Code, edit it to use the destination domain, save, and reload the public page to confirm.

• "media.json is in the export but the destination didn't apply it." The importer requires media.json at the ZIP root (database/media.json), not nested inside another folder. Some unzip-then-rezip workflows add a wrapper folder — flatten it before re-importing.

• "The success banner appears but I can't find the new files in the grid." Refresh the Media Library page — the grid is paginated and your imported rows may be on a later page. Also check that the All Files tab is selected, not a filtered view like Images. If you imported mostly documents and the filter is set to Images, switch to All Files to see every uploaded type.

• "Imported files appear in the grid but their thumbnails are broken." The thumbnail generator queues separately from the file write. On a busy site, thumbnails can take a minute to regenerate after the import returns. Reload the grid after a minute. If thumbnails are still missing after several minutes, the variant generator may not have write permission on the destination's variant subdirectories — escalate to platform.

• "The platform team is asking which selection to use." For a migration to another SGEN site: All (preserves titles, alt text, descriptions). For a quick local backup before a risky change: Files only is faster and metadata stays safe in your live database. For an agency handoff: All (the agency needs the metadata to provision a parallel site).

• "Import worked but performance is degraded after the migration." After a large import, SGEN's media indexes may need to rebuild. Most sites recover within minutes as variant thumbnails regenerate on demand. If performance stays degraded for more than an hour, ask platform to check whether the post-import media-table indexes are present and healthy.

• "The export ZIP is larger than expected." Confirm you're not including resized variants. The exporter excludes subdirectories whose names match registered size-variant keys — standard SGEN size keys are filtered automatically. If your library uses a custom size key that wasn't registered, it ships in the archive. Have platform check the registered size keys and re-run.

• "Don't rely on it for cross-tenant shared media." Import loads files into the current site only. There is no multi-site shared media library in SGEN — each site has its own uploads/ directory and its own media database table. If two of your sites need the same file, upload it once per site.

Vocabulary

Next step

After restoring or migrating a media library, walk through these checks in order. Doing them in sequence matters — a broken image on a public page is easier to diagnose before you've published new content on top of the migration.

• Browse the Media Library — open the grid in admin and confirm every expected row appears with correct titles, sizes, and thumbnails.
• Spot-check public pages — open three to five pages in an incognito window and verify every image loads. The home page, a top-selling product page, and the most recent blog post are a good sample.
• Run a baseline export — capture the post-migration state as a backup before any new uploads happen.
• Update the team backup schedule — if the migration revealed a gap in DR coverage (no recent backup, no agreed retention window), formalize a schedule now while it's fresh.
• Document the migration — note the export filename, the import summary, and any errors that came up. The next person running a migration will thank you.