Fix Odoo Assets Compilation and SCSS Errors: Complete Guide

The Assets Compilation Error

You update a custom module or install a new theme, and suddenly the Odoo web interface is broken — unstyled pages, JavaScript errors, or a complete white screen. The Odoo log shows:

ERROR odoo.addons.base.models.assetsbundle: Could not compile asset web.assets_backend
CompilationError: Invalid CSS after "...": expected "}", was end of input

# Or:
SCSS Error: Undefined variable: "$o-brand-primary"
  on line 42 of /odoo/addons/my_theme/static/src/scss/theme.scss

# Or:
FileNotFoundError: [Errno 2] No such file or directory: '/odoo/addons/web/static/src/scss/_variables.scss'

How Odoo Asset Compilation Works

Odoo bundles CSS, SCSS, and JavaScript files into asset bundles. During compilation:

1. SCSS files are compiled to CSS using libsass
2. All CSS files are concatenated and minified
3. JavaScript files are concatenated and minified
4. The compiled bundle is cached in the database

If any file in the bundle has an error, the entire bundle fails to compile.

Cause 1: SCSS Syntax Errors

The most common cause. A missing semicolon, unclosed bracket, or invalid property breaks the entire bundle.

/* BAD — missing semicolon */
.my-class {
    color: red
    background: white;
}

/* BAD — unclosed bracket */
.my-class {
    color: red;
/* missing closing } */

/* FIX: Check your SCSS files for syntax errors */
/* Use a SCSS linter or validator before deploying */

Cause 2: Undefined SCSS Variables

Referencing Odoo SCSS variables that do not exist in the current version.

/* BAD — variable name changed between Odoo versions */
.header {
    background-color: $o-brand-primary;  /* Odoo 14 */
}

/* FIX for Odoo 16+ — use CSS custom properties */
.header {
    background-color: var(--o-brand-primary);
}

/* Or define the variable yourself */
$o-brand-primary: #714B67 !default;
.header {
    background-color: $o-brand-primary;
}

Cause 3: Missing Asset Declaration in Manifest

Your SCSS or JS file exists but is not included in the asset bundle.

# In __manifest__.py:
'assets': {
    'web.assets_backend': [
        'my_module/static/src/scss/custom.scss',
        'my_module/static/src/js/custom.js',
    ],
    'web.assets_frontend': [
        'my_module/static/src/scss/website.scss',
    ],
},

Common mistake: declaring the file in the wrong bundle. Backend styles go in web.assets_backend, website/portal styles in web.assets_frontend.

Cause 4: Stale Asset Cache

Old compiled assets cached in the database conflict with new code.

# Method 1: Clear assets via URL
# Add ?debug=assets to your Odoo URL
https://your-odoo.com/web?debug=assets
# Then: Settings gear icon → Clear Assets Bundle

# Method 2: Clear via database
psql -d your_database -c "
DELETE FROM ir_attachment
WHERE name LIKE '%assets_%' AND res_model = 'ir.ui.view';"

# Method 3: Restart Odoo with --dev=xml,qweb
./odoo-bin --dev=xml,qweb  # Disables asset caching

Cause 5: Missing Node.js or rtlcss

For RTL (right-to-left) language support, Odoo needs rtlcss.

# Check if rtlcss is installed
which rtlcss

# Install it
sudo npm install -g rtlcss

# Verify
rtlcss --version

Cause 6: File Encoding Issues

SCSS files saved with wrong encoding (BOM markers, non-UTF-8) cause compilation to fail with cryptic errors.

# Check encoding
file -bi my_module/static/src/scss/custom.scss
# Should show: text/plain; charset=utf-8

# Fix: convert to UTF-8 without BOM
iconv -f UTF-8 -t UTF-8 -o fixed.scss custom.scss

Cause 7: Conflicting Module Styles

Two modules override the same SCSS variable or class, creating compilation conflicts.

/* Module A: */
$navbar-height: 50px;

/* Module B: */
$navbar-height: 60px !default;  /* Use !default to avoid conflicts */

/* The !default flag means: only set if not already defined */

Step-by-Step Fix Process

1. Enable debug mode: Add ?debug=1 to the URL
2. Check browser console: Look for specific file and line numbers in errors
3. Check Odoo logs: The compilation error shows which file failed
4. Clear asset cache: Delete cached bundles from ir_attachment
5. Restart with --dev: Run with --dev=xml,qweb,assets to disable caching
6. Validate SCSS: Use an online SCSS validator to check your file
7. Test in isolation: Temporarily remove your asset files from the manifest to confirm the base bundle compiles

Prevention

• Always use !default when defining SCSS variables in custom modules
• Test asset compilation after every change: clear cache and reload
• Use CSS custom properties (var(--name)) instead of SCSS variables when possible — they do not break compilation
• Keep SCSS files small and focused — easier to find errors
• Use a code editor with SCSS linting (VS Code + SCSS IntelliSense)