What causes "Expected hash token" in swc-project/swc?

Prefix the value with '#': 'fff' -> '#fff'.

swc-project/swc · error · Error

Expected hash token

Error message

Expected hash token

What it means

Thrown by the Parse<HexColor> impl in swc_css_parser when a hex color is expected but the current token is not a hash token. The impl checks is!(self, "#") first; an ident ('fff'), a number ('fff' after a failed escape), a string, or EOF fails immediately with this error. In normal flows AbsoluteColorBase only delegates here after seeing a '#', so hitting it usually means typed HexColor parsing was invoked on the wrong token or input position.

Source

Thrown at crates/swc_css_parser/src/parser/values_and_units/mod.rs:2428

                    ErrorKind::Expected(
                        "hash, ident (with named color or 'transparent' value) or function (with \
                         color function name) token",
                    ),
                ));
            }
        }
    }
}

impl<I> Parse<HexColor> for Parser<I>
where
    I: ParserInput,
{
    fn parse(&mut self) -> PResult<HexColor> {
        let span = self.input.cur_span();

        if !is!(self, "#") {
            return Err(Error::new(span, ErrorKind::Expected("hash token")));
        }

        match bump!(self) {
            Token::Hash { value, raw, .. } => {
                if value.chars().any(|x| !x.is_ascii_hexdigit()) {
                    return Err(Error::new(
                        span,
                        ErrorKind::Unexpected("character in hex color"),
                    ));
                }

                Ok(HexColor {
                    span,
                    value,
                    raw: Some(raw),
                })
            }
            _ => {

View on GitHub (pinned to 5176682b65)

Solutions

Prefix the value with '#': 'fff' -> '#fff'.
Re-add '#' after any normalization that strips it (e.g. shorthand expansion).
Before typed hex parsing, check the string starts with '#'.

Example fix

/* before */
a { color: fff; }

/* after */
a { color: #fff; }

Defensive patterns

Strategy: type-guard

Validate before calling

function startsWithHash(v: string): boolean {
  return v.trim().startsWith('#');
}

Type guard

fn is_hash_prefixed(v: &str) -> bool {
    v.trim_start().starts_with('#')
}

Try / catch

use swc_css_parser::error::ErrorKind;
if let Err(e) = parse_input::<Stylesheet>(src, opts) {
    if matches!(e.kind(), ErrorKind::Expected("hash token")) {
        return Err(format!("expected #hex color at {:?}", e.span()).into());
    }
    return Err(e.into());
}

Prevention

Re-add '#' after any normalization pipeline that strips it (shorthand expansion, comparison code).
Model colors as structured RGBA in code and serialize to hex only at the boundary.
Do not double-parse past a '#' the cursor already consumed.

When it happens

Trigger: Calling typed <hex-color> parsing on values like 'fff' (missing '#'), 'red', '', or when the parser cursor already consumed the '#' (double-parsing the same position).

Common situations: Code that strips '#' to normalize colors and forgets to re-add it before re-parsing, and utility functions assuming any color string is hex.

Related errors

AI-assisted analysis of swc-project/swc@5176682b65 (2026-08-17). Data as JSON: /api/errors/264d2c1066de3cd0. Report an issue: GitHub.