Please read! End of support for Xenial build image: Everything you need to know

On November 15th, 2022, Netlify will be fully removing support for the Ubuntu 16.04 (Xenial) build image. Ubuntu Xenial finished its Long Term Support period in 2021 and is no longer supported by Canonical. This means no new bug fixes and security updates, nor new versions of included software.

Builds on Xenial make up a very small percentage of total Netlify builds, but we know this is a significant change so we’re giving you time to migrate.

Timeline

DateWhat happens
September 27th, 2022 First Brownout
Builds using the Xenial build image will error for 10 minutes at a time during the following periods:
  • UTC 00:00 — 00:10
  • UTC 01:00 — 01:10
  • UTC 10:00 — 10:10
  • UTC 11:00 — 11:10
  • UTC 15:00 — 15:10
  • UTC 16:00 — 16:10
October 12th, 2022 Second Brownout
Builds using the Xenial build image will error for 10 minutes at a time during the following periods:
  • UTC 00:00 — 00:10
  • UTC 01:00 — 01:10
  • UTC 10:00 — 10:10
  • UTC 11:00 — 11:10
  • UTC 15:00 — 15:10
  • UTC 16:00 — 16:10
October 18th, 2022 Deprecation of Xenial Build image selection

Sites will no longer be able to select the Xenial build image. Upgrading to Focal after this date will be final.

October 26th, 2022 Third Brownout
Builds using the Xenial build image will error for 1 hour at a time during the following periods:
  • UTC 00:00 — 01:00
  • UTC 10:00 — 11:00
  • UTC 15:00 — 16:00
November 8th, 2022 Fourth Brownout
Builds using the Xenial build image will error for 3 hours at a time during the following periods:
  • UTC 00:00 — 03:00
  • UTC 08:00 — 11:00
  • UTC 16:00 — 19:00
November 15th, 2022 Xenial build image end of life.
Builds using the Xenial build image will fail going forward.

How do I know if my site is using Xenial?

If you’re not sure whether your site is building with Xenial then you can check in a few places:

  1. You sites list or site detail page. Sites using the Xenial image have a warning icon next to the site name.
  2. Your deploy logs. Check for a log line that says: DEPRECATION NOTICE: Builds using the Xenial build image will fail after November 15th, 2022
  3. Your site settings. Go to Site settings > Build & deploy > Continuous Deployment > Build image selection.

What’s different about the new build image?

In May of 2021, we released a new build image based on Ubuntu 20.04 (Focal). In addition to a newer version of Ubuntu Linux, it includes some version updates to included language and software dependencies.

What will happen if I don’t update my site’s build image?

Starting on the week of September 27th we will be doing a series of “brownouts”, that means builds using the Xenial image will fail during certain hours for a finite period of time. An error will be logged in the build logs informing that Xenial image is not supported.

After November 15th, 2022, any new builds using the Xenial build image will fail. We will continue to serve traffic to your existing site, and you will still be able to deploy manually via Netlify CLI, but you will not be able to run new builds of your site on Netlify until you update to a newer build image.

How do I update my build image?

You can upgrade to the latest build image in the Netlify UI under Site settings > Build & deploy > Continuous Deployment > Build image selection.

Please note that after October 18th this change will be final. Once you upgrade to Focal, you will not be able to downgrade back to Xenial.

How can I run a test build with the new image?

One way to run a test build is through the Netlify UI:

  1. From your site’s Deploys page, select the current published deploy (usually the most recent production deploy).
  2. At the top of the deploy’s log page, click the Lock to stop auto publishing button. With deploys locked, you can run new deploys without changing your published site.
  3. Click the Deploy settings button, scroll down to Build image selection, and select the Focal build image.
  4. Go back to your Deploys page and click the Trigger deploy button.
  5. The new deploy will start building. If it succeeds, click Preview deploy to visit that version of your site. If the site is working normally then you’re set! Go back to your Deploys page and click Start auto-publishing to keep builds running normally, now with their fancy new build image.
  6. If the deploy fails or the site isn’t working properly, you will need to do some troubleshooting. If you don’t have time to do that now, you can switch back to the Xenial image and Start auto-publishing again. You can repeat the steps above when you’re ready to troubleshoot, or create a new site for testing that’s linked to the same repository. Here’s how:
    1. Create a brand new site by clicking the New site from Git button on your team dashboard. Be sure to link to the same repository that you use for your existing site!
    2. Once you’ve created your new site, go to Site settings > Build & deploy > Continuous Deployment > Build image selection and select the new build image.
    3. Trigger a deploy to test the new build image.

How can I make my site work with the new image?

Generally speaking, a change in available language or software dependency versions is the cause of the error. This could be a version you set yourself or one that was set for you by default when the site was first created. Here are some general steps for troubleshooting:

  1. Check for error messages in the deploy log. They will often indicate which language or software dependency is causing the problem.

  2. Check the Focal image included software list to find which versions are available for the dependency that is causing your issue.

  3. Try setting the dependency to use an included version. Refer to the docs on managing dependencies to learn how to do this.

    Note: if the dependency version was not explicitly set by you, then it’s set to a version selected by default when you created your site. You can override this as described in the dependency management docs. Select a version already installed on the image to avoid unneeded installations.

    If you prefer not to set a version explicitly, you can “reset” your site defaults by re-linking your site repository, but please note that this will also remove any environment variables set in the Netlify UI. Be sure to copy your variables before re-linking, then re-enter them after re-linking.

  4. Run a new test build to see if it works.

  5. If it doesn’t work, and you’ve tried all available versions on the new image, you may have the option to specify a version that isn’t pre-installed on the image. Dependencies with this option are labeled in the included software list with “Any version” as one of the version options.

    1. For dependencies that don’t offer an option to download any version, you will need to update your site code to work with a version available on the new image. You can search for migration guides for the dependency version to help you identify necessary changes.

If you get through these steps and you’re still stuck, or if you have any other questions along the way, let us know!

6 Likes

How I can do that with a manually deployed site? At my site settings it looks like that:

Continuous Deployment
Settings for Continuous Deployment from a Git repository

Repository
Continuous Deployment works by connecting a Git repository to your Netlify site and keeping the two in sync. When you push to Git, we run your build tool of choice on our servers and deploy the result.
Current repository
Not linked

Do I need a Git repository?

Same issue for me (no build image selection options, just the offer to link a repository)

1 Like

I have this same issue. Following.

1 Like

Hey team!

Is there a way to bulk-update build images? I counted and have 47 sites that use the old one, and I’d love to just do a “check all” for all of them to update. It’ll be fairly tedious to do that per site.

1 Like

Same issue, I am using manual depoy via netlify CLI.

under the Build / Continuous Deployment, I can’t see anything related to Build image selection.

Where’s the Build image selection under Continuous Deployment? I can’t find it! :fearful:

I deploy manually using the drag & drop feature.

Hey @jonkantner

When you deploy manually, there is no build image selection as you are not using continuous deployment.

Okay, so I deployed a build again with the same method and didn’t see the deprecation notice in my deploy log. There’s no warning icon next to my site name, yet the email sent out a couple hours ago still insists my site is impacted. Is my site still safe despite what the email says?

I don’t believe you will see any impact to your site(s).

Team,

I have a site that I build on gatsbycloud and deploy on Netlify. The email says my sight will be impacted. I don’t think it will, but want to cofirm.

Thanks!

Hello folks :wave:

Thanks for all of your questions, I’ll try to address them all in this response.

Yesterday we sent out a deprecation notice letting some of our customers know about the need to move your existing builds to focal before the deprecation deadline.

Although we narrowed down the list to those potentially affected by this change (i.e. folks using xenial) we may have inadvertently sent you the email even though you may not be affected by this change.

Am I affected?

If you’re using our build system to deploy any particular site through our git integration you may be affected. Please reference this bullet point on how to check if you’re using xenial.

If you have a lot of sites, it can be confusing. Please make sure that no site is using xenial by checking in your site’s list for the yellow warning triangle indicator:

That means this site is affected by this change!

What do I need to do?

All instructions are available on our deprecation guideline forums post. Feel free to check that guide.

What sites are not affected

  • Sites not using the git-based builds (which include sites deployed manually)
  • Sites deployed through the API directly

We apologise for this inconvenience and are already working on improving the logic behind these emails!

Sites not using the git-based builds (ie: not linked to a git repository) won’t be shown the build image selection card in the UI:

If you have any questions or concerns let us know!

3 Likes

@cassidoo1 there’s no built-in bulk update option, but you can use this npm package created by our very own @jlengstorf ntl-focal-migrate - npm
It relies on the Netlify CLI to update sites via API calls.

2 Likes

Thanks. I must have received an email that was sent by mistake.

This saved me from a world of hurt. Awesome, thanks @jlengstorf @kito !!

2 Likes

Hi kito,
I know I’m a bit late for this post, but I couldn’t find theLock publishing to this deploy button at the top of the deploy’s log page. There’s only Lock to stop auto publishing button. Any suggestions?

This is the correct button @linchen5913.

1 Like

As @coelmay said, that’s the right button. Thanks for flagging it, I’ve updated the original post with the correct button copy.

1 Like

Support for Xenial has now ended, and all builds using this image will now fail going forward. Please follow the instructions in the original post to update your build image, and as usual let us know if you have any questions!

Hello, I am new to Netlify and working on a project created by someone else which uses Xenial build image.
I started today and figured out it has been deprecated. There’s another option for ‘Focal 20.4 (default)’, if I switch to that, will it affect the current site? Please give me suggestions to deploy changes in the existing website. Thank you.