apple/pkl · error · VmTypeMismatchException

type mismatch: value is not the expected string literal

Error message

type mismatch: value is not the expected string literal

What it means

Pkl string literal type check failure (StringLiteralTypeNode.executeLazily). A property or argument was declared with a string literal type such as `"red"|...` or a single `"literal"` type, and the runtime value did not exactly equal that literal. Pkl treats string literals as first-class types, so equality is strict and type-checked at evaluation time.

Source

Thrown at pkl-core/src/main/java/org/pkl/core/ast/type/TypeNode.java:611

    }

    public String getLiteral() {
      return literal;
    }

    @Override
    public boolean doIsEquivalentTo(TypeNode other) {
      if (!(other instanceof StringLiteralTypeNode stringLiteralTypeNode)) {
        return false;
      }
      return literal.equals(stringLiteralTypeNode.literal);
    }

    @Override
    protected Object executeLazily(VirtualFrame frame, Object value) {
      if (literal.equals(value)) return value;

      throw typeMismatch(value, literal);
    }

    @Override
    public Object createDefaultValue(
        VirtualFrame frame,
        VmLanguage language,
        SourceSection headerSection,
        String qualifiedName) {

      return literal;
    }

    @Override
    public VmTyped getMirror() {
      return MirrorFactories.stringLiteralTypeFactory.create(this);
    }

    @Override

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Compare the value character-by-character with the expected literal in the error/type position; fix the typo or casing.
2. If multiple values are valid, widen the declared type to a union of string literals (`"a" | "b"`) or to `String`.
3. Trim/normalize the input value before assignment.
4. Use an enum-like listing or type alias so all valid literals are visible in one place.

Example fix

// before
level: "debug" = "Debug"
// after
level: "debug" = "debug"   // exact literal match required

// Pkl
expected: String = "production"
if (value != expected) throw("expected literal \"production\", got: \(value)")

function isProd(value: Any): Boolean = value is String && value == "production"

// Validate literal equality before use; in embedders catch PklException with 'type mismatch: value is not the expected string literal'.

When it happens

Trigger: Assigning any string (or non-string) whose exact contents differ from the declared literal type, e.g. `mode: "produc"` where the type is `"production"`; case or whitespace differences also fail.

Common situations: Typos in enum-like string configuration, trailing whitespace or quotes pasted from docs, casing differences (`"Prod"` vs `"prod"`), or supplying a variable/interpolated string where a literal type is required.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

• type mismatch: value does not conform to declared type (clas
• type mismatch: value's class is not a subclass of expected c
• type mismatch: value is not of type Typed
• type mismatch: value is not of type Dynamic
• type mismatch: value's class differs from expected class

AI-assisted analysis of apple/pkl@f3efcbfc9b (2026-09-08). Data as JSON: /api/errors/b6492b2d560bc140. Report an issue: GitHub.