DEV Community

Cover image for Forge Custom UI blank page after deploy: Vite asset paths
Mihai Perdum
Mihai Perdum

Posted on Originally published at leanzero.net

Forge Custom UI blank page after deploy: Vite asset paths

A Forge Custom UI app built with Vite can render under forge tunnel and then show a blank page after forge deploy. The cause is Vite's default build, which writes absolute asset paths such as /assets/index-xxx.js into index.html. We reproduced it on our Jira test site on 17 November 2026, and both assets returned HTTP 422 with the body Invalid URL. Adding base: './' to vite.config.js fixed the deployed panel.

If you're new to these names: Forge is Atlassian's platform for apps that run on Atlassian's cloud, and Custom UI is the Forge option where your own HTML and JavaScript run inside an iframe. Vite is the front-end build tool that turns your source into the files Forge serves. forge tunnel serves the app from your own machine while you develop, and forge deploy uploads it to Atlassian.

People keep running into this one. On 24 July 2025 a developer posted on the Atlassian developer community that their issue panel was not working without forge tunnel. "Everything works perfectly when I run it locally using forge tunnel," they wrote. "However, after building the app and deploying it with forge deploy, the app does not appear on the issue panel." Their screenshot shows a panel with a title and an empty body, the same picture we got. The next day an Atlassian staff member asked them to hard-refresh the page and read the browser console. About two hours later a second staff member pointed at the index.html in the build output, because the assets in its head "should be using relative paths".

So we built a small panel with the current Vite React template (Vite 8.3.8) and ran it three ways. Run A was deployed with the default config. Run B was the same build under the tunnel, and run C was deployed again with the one-line change. This page has the console lines from each run so you can match them against yours, and one image path the setting didn't fix for us.

Note

Prerequisites — A Jira or Confluence Cloud site where you can install apps (we used wolfaenpak.atlassian.net, our test site). A Forge Custom UI app you can deploy, which means you're its developer or a contributor on it. We ran Forge CLI 14.1.0 on Node.js 24.15.0 with Vite 8.3.8, React 19.3.1 and @⁠forge/bridge 7.3.0, in Chrome for Testing 149. When you're done you'll have a deployed panel that renders, and a check you can run before each deploy.

[[steps]]

  1. Confirm the symptom in the browser — two failed asset requests on the cdn.prod.atlassian-dev.net host (Step 1).
  2. Check index.html for absolute paths — a leading slash in the head is the cause (Step 2).
  3. Set base: './' in the Vite config — rebuild, and the paths turn relative (Step 3).
  4. Fix root-absolute strings in your JavaScript — the setting leaves a /logo.png typed as a string alone (Step 4).
  5. Deploy and check the panel — the assets load from inside your app's folder (Step 5).

Why a Forge Custom UI app works with forge tunnel and is not working without the tunnel

forge tunnel and forge deploy serve your files from different places.

When you run forge tunnel, the Forge CLI serves the folder named in your manifest's resources entry from your own machine. In our run the panel's iframe pointed at http://localhost:8000/, and curl http://localhost:8000/assets/index-U0oGil3V.js returned 200. Your build folder is the root of that little server, so a path that starts with a slash finds its file.

After forge deploy, the same folder lives on Atlassian's content delivery network, several folders deep. The iframe URL we saw looked like this (ids replaced):

Two boxy robots on a cobalt blue background. One stands on flat ground dropping a parcel straight into a low open crate; the other stands on top of a wobbly stack of five crates with a wooden ladder leaning against it, far from a glowing parcel on a pole to the right.

https://<app-host>.cdn.prod.atlassian-dev.net/<app id>/<environment id>/<per-deploy id>/panel/_ctx_<blob>/
Enter fullscreen mode Exit fullscreen mode

panel is the resource key from our manifest. The first id matched the app id in manifest.yml. The second matched the development environment in forge environments list. The third changed between our two deploys, so it's probably a per-deploy id (Atlassian's docs don't name it). That means /assets/index-U0oGil3V.js asks for a file at the top of the host, outside your app, and ./assets/index-U0oGil3V.js asks for one next to index.html. Atlassian's Custom UI page says the same in its Accessing static assets section: "instead of including an image at "/assets/image.png", you should use "./assets/image.png"".

The Vite base demo panel rendered on work item LZPT-186 under forge tunnel, with /logo.png, ./logo.png and import logo all marked loaded

Here is what runs A, B and C did. Between A and B we changed how the app was served and left the build alone.

Run Vite config Served by Panel Asset requests
A default forge deploy title and DEV lozenge, empty body 2 of 2 returned 422
B default forge tunnel fully rendered 4 of 4 returned 200
C base: './' forge deploy rendered JS and CSS returned 200

Nothing warned us on the way to run A. forge deploy ran its lint and printed No issues found. followed by ✔ Deployed. I think that's a big part of why this question keeps coming back on the forum.

Step 1. Confirm the symptom: 422 or 403 on the Custom UI static assets

Start by making sure this is your problem. The console tells you in a minute.

  1. In your browser, open the page that holds your app (for us, a work item with the panel on it). The panel shows its title and an empty body.
  2. Open the developer tools and select the Console tab, then reload the page. Failed requests are listed in red.
  3. Look for requests to a host ending in cdn.prod.atlassian-dev.net whose path starts right at /assets/ (or /static/), with no ids in between.

You should see something like this, one line per script or stylesheet in your index.html:

Failed to load resource: the server responded with a status of 422 ()   https://<app-host>.cdn.prod.atlassian-dev.net/assets/index-nqMpL4T3.css
Failed to load resource: the server responded with a status of 422 ()   https://<app-host>.cdn.prod.atlassian-dev.net/assets/index-U0oGil3V.js
Enter fullscreen mode Exit fullscreen mode

In the Network tab, each of those responses is 11 bytes long and says Invalid URL. Our iframe's own document loaded. What failed were the two files it asked for by absolute path.

The Vite base demo panel on a Jira work item, showing its title and a DEV lozenge with nothing underneath, above Jira's Agent sessions and Activity sections

Your status code may differ. Atlassian's troubleshooting list files this cause under "403 forbidden error", and a 2022 thread pasted net::ERR_ABORTED 403 for it. We got 422 in Chromium. If the URL in your console starts at /assets/ right after the host, carry on to Step 2 whatever the number is.

Step 2. Check index.html for absolute paths before you deploy

Now look at what your bundler wrote. You can do this on your machine, before any deploy.

  1. In a terminal, go to your Custom UI folder (ours is static/panel).
  2. Run npm run build. Vite writes the dist folder.
  3. Print the built entry file with cat dist/index.html.
  4. Read the src and href values in the head.

With the default Vite config, we got this:

<link rel="icon" type="image/svg+xml" href="/favicon.svg" />
<script type="module" crossorigin src="/assets/index-U0oGil3V.js"></script>
<link rel="stylesheet" crossorigin href="/assets/index-nqMpL4T3.css">
Enter fullscreen mode Exit fullscreen mode

All three paths start with a slash. Vite is doing what it's told: its base option defaults to /, which is right for a site served from the top of its own domain and wrong for a Forge resource.

This one-liner prints any root-absolute path in the built file and prints nothing when the file is clean:

grep -nE '(src|href)="/' dist/index.html
Enter fullscreen mode Exit fullscreen mode

On our default build it printed the three lines from the head:

5:    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
8:    <script type="module" crossorigin src="/assets/index-U0oGil3V.js"></script>
9:    <link rel="stylesheet" crossorigin href="/assets/index-nqMpL4T3.css">
Enter fullscreen mode Exit fullscreen mode

Step 3. The fix for a Forge Custom UI app built with Vite: base: './'

Vite's docs describe ./ as the value "for embedded deployment", and a Forge iframe is exactly that.

  1. Open vite.config.js (or vite.config.ts) in your Custom UI folder and add base: './', inside defineConfig:
import react from '@vitejs/plugin-react'
import { defineConfig } from 'vite'

export default defineConfig({
  base: './',
  plugins: [react()],
})
Enter fullscreen mode Exit fullscreen mode
  1. Run npm run build again. Vite rewrites dist/index.html.
  2. Run cat dist/index.html and read the head once more.

You should see relative paths now:

<link rel="icon" type="image/svg+xml" href="./favicon.svg" />
<script type="module" crossorigin src="./assets/index-BibfWtNU.js"></script>
<link rel="stylesheet" crossorigin href="./assets/index-nqMpL4T3.css">
Enter fullscreen mode Exit fullscreen mode

Our JavaScript file got a new hash (U0oGil3V became BibfWtNU) and the CSS file kept its name. Vite's build guide explains that a relative base makes "all generated URLs to be relative to each file", so images you import in your code are covered too.

Step 4. Fix the paths you typed in your JavaScript (base doesn't touch /logo.png)

I didn't expect this next result. Vite's base setting rewrites the URLs Vite processes during the build, and its build guide lists them: "JS-imported asset URLs, CSS url() references, and asset references in your .html files". A path you type as a string in your JavaScript, or in JSX (the HTML-like markup inside a React component), stays as you wrote it.

On an emerald green background, a factory robot runs a paint roller over a row of boxes on a conveyor, stamping each with a fresh blank yellow label, while a second robot beside the machine holds up two hand-painted wooden signs that the roller passes straight over; a bare light bulb glows above the first robot.

We put the same image into the panel with each kind of reference, to see which ones survive a deploy:

Reference in the component Under forge tunnel Deployed with base: './'
<img src="/logo.png"> (file in public/) loaded failed, 422 Invalid URL
<img src="./logo.png"> (same file) loaded loaded
import logo from './assets/hero.png' loaded loaded

Vite's asset guide tells you to reference files in public/ "using root absolute path". Written as a string in our JSX, that was the form that failed once deployed.

  1. In your editor, search the JavaScript files in your src folder for src="/ and href="/. Each hit is a path that will leave your app's folder once deployed.
  2. Change each one to start with ./, or import the file and use the imported value. After the next build, the file loads from your app's folder.

Vite also documents import.meta.env.BASE_URL for building such a URL at runtime. We didn't run that variant.

Step 5. Deploy and check the panel

  1. In the app's root folder, run forge deploy -e development. The CLI prints ✔ Deployed. We didn't need forge install --upgrade for this change.
  2. In the browser, reload the page with your app, with the developer tools still open. The panel renders.
  3. In the Network tab, select one of the asset requests and read its URL.

You should see status 200, and a URL that keeps the long app path in front of assets/:

200  https://<app-host>.cdn.prod.atlassian-dev.net/<app id>/<environment id>/<per-deploy id>/panel/_ctx_<blob>/assets/index-BibfWtNU.js
Enter fullscreen mode Exit fullscreen mode

The Vite base demo panel rendered on work item LZPT-186, with three image rows: /logo.png marked FAILED with a broken image icon, ./logo.png and import logo both marked loaded

If the panel has content and no request in the console goes to /assets/ directly under the host, you're done.

The tunnel still serves the fixed build, by the way. We ran forge tunnel again afterwards, and curl http://localhost:8000/ returned the relative-path index.html with status 200, as did both asset files. That was a curl check; the panel wasn't reopened in the browser for it.

Create React App and rsbuild: the same relative-path fix when a Forge app fails in production

Vite isn't special here. Any bundler that assumes it owns the root of a domain produces the same empty panel. Our runs covered Vite. What follows comes from each tool's documentation and from public threads.

Create React App. Atlassian's own Build a Custom UI app in Jira tutorial uses create-react-app. Atlassian's troubleshooting list says to set "homepage": "./" in package.json. The Create React App deployment page writes it as "homepage": "." and says this makes "all the asset paths … relative to index.html". The thread "My Forge App only Loads when I'm Tunneling the app from my local pc" had 2,710 views when we read it on 17 November 2026. In it, a second developer replied in April 2021 that adding "homepage": "." fixed the same symptom for them. (The original poster's own cause turned out to be a react-router setting, so read past the accepted answer.)

rsbuild. In the thread "Forge app fails in production", a developer who had moved from craco to rsbuild wrote in October 2025 that the paths in index.html had to be relative, and added output: { assetPrefix: './' }. They said it then worked in production, and that the app still didn't work through the tunnel from the build folder (only through a port). The rsbuild docs call a relative assetPrefix "not recommended" and offer 'auto', which generates relative paths based on file location.

A stray base tag. In January 2026 another developer with a Vite Custom UI reported the message was blocked because of a disallowed MIME type ("") on /assets/index-<hash>.js. Their fix was base: './' plus removing a <base href="/"> tag from index.html.

forge tunnel with the Vite dev server: tunnel.port, and two things we hit

Run B used the built dist folder, which means a rebuild after each change. You can point the tunnel at Vite's dev server instead. Atlassian's tunneling page documents a tunnel block on the resource (the manifest's Resources reference page doesn't list it):

resources:
  - key: panel
    path: static/panel/dist
    tunnel:
      port: 5173
Enter fullscreen mode Exit fullscreen mode

On Forge CLI 14.1.0 the tunnel picked this block up without a redeploy in our run. Atlassian's page says to deploy after a manifest change, so run forge deploy if yours doesn't.

With vite --port 5173 --strictPort running next to forge tunnel, our panel rendered from the dev server and the console showed [vite] connected..

Styling broke first. Our panel came up unstyled, and the console said why: Applying inline style violates the following Content Security Policy directive 'style-src 'self' …. Vite's dev client injects CSS as inline styles, and Forge's content security policy for Custom UI (the browser rule that says which scripts and styles a page may run) blocked them. The deployed build wasn't affected, because there the CSS is a separate file. Atlassian's content security page documents a permissions.content.styles entry with unsafe-inline to allow inline CSS. We haven't tried it on this error, and that's where I'd look next.

Chrome was the other problem. In headless Chrome 149 the tunnel iframe didn't load at all until we granted the local-network-access permission. Until then, Jira's page logged The target origin provided ('http://localhost:8000') does not match the recipient window's origin ('null'). Chrome announced a permission prompt for requests from public pages to local addresses, launching in Chrome 142. So if your tunnel shows an empty frame in a recent Chrome, look for a blocked local network permission on the Jira tab.

If it didn't work

What you see Where What it means
Failed to load resource: the server responded with a status of 422 () on …cdn.prod.atlassian-dev.net/assets/… Console, deployed app A root-absolute path in index.html. Steps 2 and 3.
The same 422 on one image or font after the fix Console, deployed app A path typed as a string in your JavaScript. Step 4.
net::ERR_ABORTED 403 on …/static/css/main.<hash>.css Console, deployed app The same cause, as reported in a 2022 thread. Check your built index.html (Step 2).
was blocked because of a disallowed MIME type ("") Console, deployed app Reported in January 2026 by a developer who removed a <base href="/"> tag from index.html and also set base: './'.
Applying inline style violates the following Content Security Policy directive Console, tunnel with dev server Forge's content security policy blocks the dev server's inline CSS. The deployed build is fine.
does not match the recipient window's origin ('null') Console of the Jira page, tunnel The browser blocked the iframe to localhost. Check the local network permission.

If your console shows none of these, start where Atlassian staff started in the 2025 thread: hard-refresh the page to rule out the cache, then read the console again.

What you have now, and what we left out

[[takeaways]]

  • Your Custom UI build writes relative paths into index.html, and the deployed panel renders.
  • You have a grep check to run on dist/index.html before each forge deploy.
  • Not covered by that check: a root-absolute string in your JavaScript, which lives outside index.html (Step 4).

By default grep exits 0 when it finds a path and 1 when the file is clean, which is the wrong way round for a pipeline. If you deploy your Forge app through CI/CD, wrap it like this so a bad build stops the job:

test -f dist/index.html || exit 1
if grep -nE '(src|href)="/' dist/index.html; then exit 1; fi
Enter fullscreen mode Exit fullscreen mode

To confirm it's wired the right way, save the two lines as check-paths.sh in your Custom UI folder and run bash check-paths.sh; echo $? on both builds (pasted straight into a terminal, the bare exit 1 would close it). On our default build it printed the three lines and exited 1, and on the fixed build it printed nothing and exited 0.

Our measurements come from one setup: Forge CLI 14.1.0, Vite 8.3.8 with the React template, a jira:issuePanel, and Chromium. Firefox and Forge CLI 15.1.0 (it refused our Node.js version) are outside it.

If you're building more with Custom UI, two of our other tutorials pick up from here: uploading and downloading files with the Forge Object Store and dark mode in Forge Custom UI. Would you like a test to catch the empty panel before a person does? We wrote up how we run end-to-end UI tests against a deployed Forge app with Playwright.

Did you get a status code other than 422 or 403 for this? I'd like to know which browser and which bundler you were on.


Originally published on leanzero.net. More Atlassian, Forge and local-AI write-ups at leanzero.net/blog, and if you're planning a migration or a Forge app, that's what we do: leanzero.net/services.

Top comments (0)