instructure/canvas-lms · critical

# does not exist. You need to run `yarn run build:css`…

Error message

#{file.expand_path} does not exist. You need to run `yarn run build:css` before you can serve css.

What it means

brandable_css reads a prebuilt manifest (bundles_with_deps JSON) produced by the frontend build to resolve css bundle checksums. In production it raises this error if that file is missing, because serving pages without built css would break all styling. Dev/test gets a placeholder checksum instead.

Solutions

  1. Run yarn run build:css (in the web container per repo conventions) to generate the manifests
  2. Rebuild/republish the production Docker image including the frontend build artifacts
  3. Verify the CONFIG['paths']['bundles_with_deps'] file exists after the build before starting Rails
  4. In CI, add a step asserting the manifest file exists prior to deploy

Example fix

// before
file.exist? => false, Rails.env.production? => raise
// after
$ yarn run build:css   # regenerates public/dist/* and the checksum manifests
Defensive patterns

Strategy: fallback

Validate before calling

path = APP_ROOT.join(CONFIG['paths']['bundles_with_deps'])
raise 'css not built' unless path.exist?

Try / catch

begin
  BrandableCSS.combined_checksums
rescue RuntimeError => e
  raise unless e.message.include?('build:css')
  fallback_checksum
end

Prevention

When it happens

Trigger: Booting or serving a production Canvas instance whose public/dist css artifacts were never built — combined_checksums is invoked when APP_ROOT.join(CONFIG['paths']['bundles_with_deps']) does not exist and Rails.env.production?.

Common situations: Deploying from a checkout without running yarn run build:css; Docker/production image built without the frontend build step; clearing public/dist as part of a clean and then starting Rails.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

AI-assisted analysis of instructure/canvas-lms@1c9f0bb801 (2026-09-15). Data as JSON: /api/errors/7ac99c01ad884c71. Report an issue: GitHub.

Appendix: source

Thrown at lib/brandable_css.rb:286

      @variants ||= CONFIG["variants"].keys.freeze
    end

    def brandable_variants
      @brandable_variants ||= CONFIG["variants"].select { |_, v| v["brandable"] }.map { |k, _| k }.freeze
    end

    def combined_checksums
      if defined?(ActionController) && ActionController::Base.perform_caching && defined?(@combined_checksums)
        return @combined_checksums
      end

      file = APP_ROOT.join(CONFIG["paths"]["bundles_with_deps"])
      if file.exist?
        @combined_checksums = JSON.parse(file.read).transform_values do |v|
          v.symbolize_keys.slice(:combinedChecksum, :includesNoVariables)
        end.freeze
      elsif defined?(Rails) && Rails.env.production?
        raise "#{file.expand_path} does not exist. You need to run `yarn run build:css` before you can serve css."
      else
        # for dev/test there might be cases where you don't want it to raise an exception
        # if you haven't ran `brandable_css` and the manifest file doesn't exist yet.
        # eg: you want to test a controller action and you don't care that it links
        # to a css file that hasn't been created yet.
        default_value = { combinedChecksum: "Error: unknown css checksum. you need to run brandable_css" }.freeze
        @combined_checksums = Hash.new(default_value).freeze
      end
    end

    # javascript needs to know the checksums of the available variants for each
    # handlebars template so that it loads the corresponding stylesheet when the
    # template is rendered at runtime
    def handlebars_index_json
      if defined?(ActionController) && ActionController::Base.perform_caching && defined?(@handlebars_index_json)
        return @handlebars_index_json
      end

View on GitHub (pinned to 1c9f0bb801)