JS SyntaxError

Why one syntax error breaks a whole file

Before running a script, the browser parses all of it to understand its structure. If the parser meets something that is not valid JavaScript, it stops, reports a SyntaxError, and discards the file. Not one line of it runs, including the lines above the mistake. That makes a syntax error very different from a runtime error, which only interrupts the piece of work that was under way.

The damage depends on how your scripts are packaged. On a site that bundles everything into one file, a single stray character removes every feature. On a site with many small files, only the features in the broken file disappear, which can make the problem harder to spot: the page looks fine until someone tries the one thing that no longer works.

JSON is a special case. JSON.parse also throws a SyntaxError when it is given text that is not valid JSON, but that happens while the code is running, so only the code waiting for that data fails. The fix for those is usually on the server, as explained below.

What each message is telling you

Firefox and Safari word some of these differently. Firefox, for example, reports expected expression, got '}' and unterminated string literal. The position is what matters: every browser points at the place where the parser gave up, which is at or just after the real mistake.

The most common cause: the file is not JavaScript

A syntax error at line 1, column 1 almost never means the code is wrong. It means the browser received something other than code. Check what the server actually sent before opening an editor.

curl -sI https://example.com/assets/app.4c2e.js
# Look for: HTTP/2 200 and content-type: application/javascript (or text/javascript)

curl -s https://example.com/assets/app.4c2e.js | head -c 300
# If this starts with <!DOCTYPE html> the server returned a web page, not a script

Typical reasons the server returns a page instead of a script:

• A deploy renamed the bundle and a cached copy of the HTML still asks for the old name. Many servers and single-page app set-ups answer unknown addresses with the home page and a 200 status, so the error looks like a syntax problem rather than a missing file.
• A security or bot-protection layer served a challenge page to the request.
• Maintenance mode or a login wall applied to the assets folder as well as the pages.
• A wrong path in a theme setting, such as a relative address that breaks on deeper pages.

The same pattern shows up with data. Unexpected token '<', "<!DOCTYPE "... is not valid JSON means code asked an API for JSON and received an HTML error page. Fix the endpoint or the address, and make the calling code check the response status before parsing.

Modern syntax and older browsers

JavaScript gains new syntax every year. Code using optional chaining, nullish coalescing, class fields or top-level await is perfectly valid, but a browser released before that feature arrived treats it as a syntax error. The usual victims are older iPhones and iPads that cannot update Safari, older smart TVs, in-app browsers and locked-down corporate machines.

The fix is to decide which browsers you support and let the build tool compile down to that level. Most tools read the same shared setting, a Browserslist query, either in package.json or a .browserslistrc file:

{
  "browserslist": [
    "> 0.5% in GB",
    "last 2 versions",
    "not dead",
    "iOS >= 15"
  ]
}

Babel, SWC and Autoprefixer read this directly. Some bundlers use their own setting instead: esbuild takes a --target list such as es2020,safari15, and Vite uses build.target. Whatever the tool, check what it actually outputs by searching the built file for ?. or ?? after changing the target.

Two points catch people out. First, compiling handles syntax but not missing functions: a browser without structuredClone still needs a polyfill, and that failure is a runtime error, not a syntax error. Second, many build set-ups skip compiling files in node_modules, so a dependency that ships modern syntax can slip through untouched. Check your build tool's documentation for how to include specific packages in compilation.

The fix, step by step

Pasted snippets, curly quotes and invisible characters

On WordPress, Shopify and similar platforms, many syntax errors are not written by a developer at all. They arrive when someone copies a tracking snippet from an email, a PDF or a word processor and pastes it into a settings box.

• Curly quotes. Word processors and some email apps turn straight quotes into typographic ones. JavaScript does not accept them, and the result is Invalid or unexpected token.
• Invisible characters. Non-breaking spaces and zero-width characters look like ordinary spaces but are not always accepted where the code expects them. Retyping the line in a plain text editor removes them.
• Visual editors. Pasting code into a rich text block can wrap it in paragraph tags or convert characters into HTML entities. Use a dedicated code or HTML block, or the theme's header and footer code setting.
• Truncated snippets. Some fields have a character limit and cut long snippets off, leaving an unclosed function.
• Snippets inside snippets. A tag manager custom HTML tag needs its own script tags; a theme field that already wraps content in a script tag does not. Doubling or missing them breaks the snippet.

// Broken: typographic quotes from a document
gtag(‘config’, ‘G-XXXXXXX’);

// Fixed: straight quotes
gtag('config', 'G-XXXXXXX');

A pre-release check that catches syntax errors

Your build tool already parses every file it bundles, so a clean build is itself a syntax check for your own code. The gaps are files that skip the build: hand-edited scripts in a theme folder, files copied from a vendor, and inline scripts in templates. A few lines in your deployment pipeline close those gaps.

# Fail the release if any shipped script does not parse
for f in dist/assets/*.js public/js/*.js; do
  node --check "$f" || exit 1
done

# Lint the source as well
npx eslint "src/**/*.js"

node --check parses a file without running it. It treats .js files according to the nearest package.json, so files using import may need the .mjs extension or a package type of module to be checked correctly. For inline scripts in HTML templates, the simplest safeguard is to move them into separate files where these checks can reach them.

Edge cases

• The error appears only for some visitors. That usually means old browsers are receiving modern syntax, or one CDN edge is serving a stale or truncated copy. Check the user agents in your error monitoring and purge the CDN.
• A minifier created the error. Rare with current tools, but it happens with old minifier plugins on CMS platforms. If the source parses and the minified file does not, switch the minify option off for that file and report it.
• Inline JSON-LD breaks. Structured data blocks are not run as JavaScript, so invalid JSON there does not show as a console syntax error; search engines simply ignore the block. Validate it separately.
• A reserved word used as a name. Older code that uses words such as await or enum as variable names can fail once it is loaded as a module or in strict mode.