<!-- Markdown twin of https://pixelvault.dev/blog/confluence-export-images-broken/ -->

[← Back to blog](/blog/)

By [PixelVault](/about/) November 7, 2026

# Confluence export images broken? Get them out and re-host them

You moved pages out of Confluence (to Markdown, a docs site, GitHub, Notion) and the text came across fine, but the images are broken boxes or a login prompt. The images were never in the page. Here is where they are and how to bring them along.

## Why the images break

An image in a Confluence page is an **attachment** on that page. The page body only references it, and the reference resolves to a URL like `https://your-site.atlassian.net/wiki/download/attachments/123456/diagram.png`.

That URL only works for someone logged in to your Confluence site who is allowed to see the page. Inside Confluence that's everyone reading, so you never notice. Outside it, a reader (or a build server, or a crawler) gets redirected to the Atlassian login page, and an `<img>` tag can't display a login page.

So you see broken images whenever the content leaves Confluence but the image references don't change:

-   **Markdown converters** that read pages through the API and keep the attachment URLs as they are.
-   **Copy and paste** from a Confluence page into another editor, which brings the URLs, not the files.
-   **A site or wiki you are retiring.** Even links that worked for logged-in readers die when the Confluence site is closed.
-   **Migrations into Confluence** can lose attachments too: Atlassian's own tracker has reports of "Attachment File Not Found" after moving to Cloud. If that's your problem, re-check the attachment counts before you go further.

## Step 1: get the image files out

You need the actual files, because nothing outside Confluence can fetch them through the login. There are two ways:

-   **HTML space export.** In the space, go to Space settings and export the space as HTML. The ZIP contains a page per HTML file plus the attachment files, in folders keyed by page ID (the files themselves may be named by attachment ID rather than their original name). This is the easiest source for a migration, because the exported HTML already points at those local files.
-   **The REST API.** List each page's attachments (`/wiki/rest/api/content/<pageId>/child/attachment`) and download each one using an [Atlassian API token](https://id.atlassian.com/manage-profile/security/api-tokens). Use this if your converter already produced Markdown with Confluence URLs in it and you only need the files.

\# One attachment, straight from Confluence Cloud \# (use an API token, not your password). The download link is the \# attachment's \_links.download, relative to /wiki. WIKI="https://your-site.atlassian.net/wiki" curl \-fL \--create-dirs \-u "you@example.com:$ATLASSIAN\_API\_TOKEN" \\ "$WIKI/download/attachments/123456/diagram.png" \\ \-o attachments/123456/diagram.png

Atlassian's own advice for pulling every attachment in a space is the same pair of options. Whichever you use, count the files against the attachment listing: migrations are known to drop some without an error.

## Step 2: convert the pages

Turn the exported HTML into Markdown with the tool you already use for the migration, for example `pandoc -f html -t gfm-raw_html page.html -o page.md`. The `-raw_html` part matters: Confluence puts sizes and classes on its images, and without it pandoc keeps them as HTML `<img>` tags instead of Markdown images. Check one page: the image links should now be Markdown images with **local paths** into the export folder, not `atlassian.net` URLs.

Local paths work on your machine and break everywhere else: on a docs site whose build doesn't copy the folder, in a GitHub wiki, in Notion, in an email. Step 3 replaces them with real URLs.

## Step 3: re-host the images and rewrite the links

This script walks a folder of Markdown files, finds every image that points at a local file, uploads each file to PixelVault once, and rewrites the link to the permanent `img.pixelvault.dev` URL. It needs Node 18 or later and an API key from a [free account](/signup/):

**Before you run it:** Confluence attachments are login-only, and the new URLs are public: anyone who has a link can open the image. That is what makes them work outside Confluence, but it is a change in who can see them. If some pages hold confidential material, run the script only on the folders you are fine sharing that way.

rehost-local-images.mjs

// Usage: PIXELVAULT\_API\_KEY=... node rehost-local-images.mjs ./export // Finds Markdown images that point at local files, uploads each file to // PixelVault once, and rewrites the link in place. rehosted.json keeps the // file -> URL map, so a re-run only uploads what is new. import { readFile, writeFile, readdir } from "node:fs/promises"; import { basename, dirname, join, resolve } from "node:path"; if (!process.env.PIXELVAULT\_API\_KEY) { console.error("Set PIXELVAULT\_API\_KEY first."); process.exit(1); } const root = process.argv\[2\] ?? "."; const MAP = "rehosted.json"; const map = JSON.parse(await readFile(MAP, "utf8").catch(() => "{}")); async function\* markdownFiles(dir) { for (const entry of await readdir(dir, { withFileTypes: true })) { const path = join(dir, entry.name); if (entry.isDirectory()) yield\* markdownFiles(path); else if (entry.name.endsWith(".md")) yield path; } } async function upload(file) { const form = new FormData(); form.append("file", new Blob(\[await readFile(file)\]), basename(file)); form.append("folder", "migration"); form.append("dedupe", "true"); const res = await fetch("https://api.pixelvault.dev/v1/images", { method: "POST", headers: { Authorization: \`Bearer ${process.env.PIXELVAULT\_API\_KEY}\` }, body: form, }); if (!res.ok) throw new Error(\`${file}: ${res.status} ${await res.text()}\`); return (await res.json()).data.url; } // "my%20shot.png" -> "my shot.png", but keep a literal "100% done.png" as is. function decodePath(path) { try { return decodeURIComponent(path); } catch { return path; } } // !\[alt\](path), !\[alt\](<path with spaces>), !\[alt\](path "title") and one level // of parentheses inside a path, as in !\[alt\](diagram(v2).png) const IMAGE = /!\\\[(\[^\\\]\]\*)\\\]\\((<\[^>\]+>|(?:\[^()\\s\]|\\(\[^()\\s\]\*\\))+)(\\s+"\[^"\]\*")?\\)/g; for await (const md of markdownFiles(root)) { const text = await readFile(md, "utf8"); let out = text; for (const \[match, alt, rawTarget, title = ""\] of text.matchAll(IMAGE)) { const target = rawTarget.replace(/^<|>$/g, ""); if (/^\[a-z\]\[a-z0-9+.-\]\*:/i.test(target)) continue; // already a URL const file = resolve(dirname(md), decodePath(target.split(/\[?#\]/)\[0\])); try { map\[file\] ??= await upload(file); } catch (err) { console.error(\`skipped ${target} in ${md}: ${err.message}\`); continue; } out = out.replace(match, () => \`!\[${alt}\](${map\[file\]}${title})\`); } if (out !== text) { await writeFile(md, out); console.log(\`rewrote ${md}\`); } await writeFile(MAP, JSON.stringify(map, null, 2)); }

-   It edits files in place, so run it on a copy (or a git branch) of the converted export.
-   It keeps a `rehosted.json` map, and uploads with `dedupe`, so you can stop and re-run it, and an image used on ten pages is uploaded once.
-   It handles Markdown image syntax. If your converter left raw `<img src>` tags, convert those first or extend the pattern.
-   Each image can be up to 5 MB on the free plan (10 MB on Starter, 15 MB on Pro). Files it can't upload are listed and skipped, not lost.

When it's done, search the output for three things:

-   `<img`: HTML image tags the script doesn't rewrite.
-   `](attachments/`: a local image that failed to upload. The script printed why.
-   `atlassian.net/wiki/download`: an image the converter linked remotely instead of exporting. The script leaves URLs alone, so turn these into local paths first: download the files with the API as in Step 1, into an `attachments/` folder next to the Markdown, then point the links at them and run the script again:

\# Point remote Confluence image links at the files you downloaded \# (attachments/<pageId>/<file>, next to the Markdown), then re-run the script. \# The script ignores the ?version=…&api=v2 part of each link. OLD='https://your-site\\.atlassian\\.net/wiki/download/attachments/' sed \-i.bak "s#$OLD#attachments/#g" \*.md

## If an agent is doing the migration

Content migrations are increasingly run by coding agents, and they tend to stop at "the Markdown converted", because nothing fails. Give the agent the three steps above as the definition of done, plus the final `atlassian.net` search. With the [PixelVault MCP server](/blog/mcp-image-hosting/) connected it can upload the files itself.

Only a handful of images? Download them from Confluence while logged in and turn each into a link with the [image to URL tool](/tools/image-to-url/). No signup to try it; save them to a free account to keep them.

## Same problem, other sources

-   [GitHub private-repo attachments](/blog/private-user-images-githubusercontent-broken/) expire minutes after they are rendered.
-   [Notion](/blog/host-notion-api-images/) API image URLs expire after an hour, and Notion exports leave you with local paths.
-   [imgbox](/blog/imgbox-is-down-rescue-images/) and [Imgur](/blog/fix-uk-blocked-imgur-images/) embeds break when the host blocks or drops them.

## More in Rescue broken image links

-   [ImageBam or ImageVenue down? Check first, then recover](/blog/imagebam-imagevenue-down-check-and-recover/) Blank embeds are usually a block, a hotlink refusal, or DNS — not an outage. Here's how to tell which in thirty seconds, what's genuinely recoverable when a host really is dying, and how to stop depending on the answer.
-   [imgbox down? Is it coming back — and how to save your images](/blog/imgbox-is-down-rescue-images/) "Thumbnail temporarily unavailable", 503s and timeouts — what's actually happening to imgbox, whether your images are gone, and how to rescue what you still can.
-   [Imgur images not loading in WordPress? Fix them in one click](/blog/imgur-images-not-loading-wordpress/) Imgur images in your posts turned into blank boxes — from the UK block, deletions, or hotlink limits. Here's a free WordPress plugin that fixes them instantly, and can copy them into storage you own, out of Imgur's reach.

[All posts in Rescue broken image links →](/blog/topics/rescue/)
