Upgrade (not-so-much) Required

If you’re starting up one of the Astro starter examples, or loading your own project in one of the online cloud coding environments (e.g. CodeSandbox, Gitpod, Forestry) then you might see the following “Upgrade Required” message in the live preview:

Window preview in CodeSandbox is white page with only the text 'Upgrade Required' and I have handwritten in blue text 'This is a lie!' Below, CodeSandbox has a toast message pop up that says 'Port 3000 Opened - The server is listening on port 3000, do you want to open it?' And I have handwritten a big YES pointing to the button that says, Open Browser pane

This is an unfortunately misleading message, because there’s nothing you need to upgrade. All you have to do is switch to a different port and you’ll see that everything is (should be!) working just fine.

Most of the time, you will want this to be port 3000. As you can see in the above screenshot, CodeSandbox knows it should open port 3000 for your Astro project, but it doesn’t always treat that as the main port. There was a user in the Astro Discord reporting this problem when using Forestry CMS, and they discovered that they actually needed to force port 8080 in order to see their preview.

Your astro.config.mjs file probably includes port 3000 as the port to run the dev server on:

export default {
  projectRoot: '.',
  pages: './src/pages',
  dist: './dist',
  public: './public',
  buildOptions: {
    site: 'https://rainsberger.ca',
    sitemap: true,
  },
  devOptions: {
    port: 3000,
  },
  renderers: ['@astrojs/renderer-react'],
};

In CodeSandbox, you can create a sandbox.config.json file to specify the port (and the version of node, because the default version may be too low for Astro):

{
  "view": "browser",
  "container": {
    "port": 3000,
    "node": "14"
  }
}

Now, any time this project is opened in CodeSandbox, port 3000 will be used as the main port by default, and you should not see this error message again.

Interpreting the "Upgrade Required" message in live web preview of Astro

Upgrade (not-so-much) Required