{"record":{"id":"b50e487749181f99","repo":"apple/pkl","slug":"type-mismatch-value-is-not-one-of-the-expected-st","errorCode":null,"errorMessage":"type mismatch: value is not one of the expected string literals","messagePattern":"type mismatch: value is not one of the expected string literals","errorType":"exception","errorClass":"VmTypeMismatchException","httpStatus":null,"severity":"error","filePath":"pkl-core/src/main/java/org/pkl/core/ast/type/TypeNode.java","lineNumber":1164,"sourceCode":"\n    @Override\n    public VmTyped getMirror() {\n      return MirrorFactories.unionOfStringLiteralsTypeFactory.create(this);\n    }\n\n    public VmList getElementTypeMirrors() {\n      var builder = VmList.EMPTY.builder();\n      for (var literal : stringLiterals) {\n        builder.add(MirrorFactories.stringLiteralTypeFactory2.create(literal));\n      }\n      return builder.build();\n    }\n\n    @Override\n    protected Object executeLazily(VirtualFrame frame, Object value) {\n      if (contains(value)) return value;\n\n      throw typeMismatch(value, stringLiterals);\n    }\n\n    @TruffleBoundary\n    private boolean contains(Object value) {\n      //noinspection SuspiciousMethodCalls\n      return stringLiterals.contains(value);\n    }\n\n    @Override\n    protected PType doExport() {\n      return new PType.Union(\n          stringLiterals.stream().map(StringLiteral::new).collect(Collectors.toList()));\n    }\n\n    @Override\n    @TruffleBoundary\n    public boolean doIsEquivalentTo(TypeNode other) {\n      if (!(other instanceof UnionOfStringLiteralsTypeNode unionOfStringLiteralsTypeNode)) {","sourceCodeStart":1146,"sourceCodeEnd":1182,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-core/src/main/java/org/pkl/core/ast/type/TypeNode.java#L1146-L1182","documentation":"Pkl multiple string-literal type check failure. The declared type is a union of string literals (e.g. `\"a\" | \"b\" | \"c\"`, amenable typecheck via `contains`), and the runtime value was not any of the accepted literals. Unlike error 671 (single literal), this node validates against a whole set of string literals.","triggerScenarios":"Assigning a string not present in the declared literal union (typo, casing, unsupported enum member); assigning a non-string value to a string-literal-union property.","commonSituations":"Enum-like config fields (log levels, environments, regions) receiving an unsupported value; adding a new environment name without extending the union type; case differences from environment variables.","solutions":["Use one of the exact literals listed in the declared union type.","Extend the union type to include the new valid literal (`\"prod\" | \"staging\" | \"dev\"`).","Normalize input casing/whitespace before assignment.","Replace the union with a type alias or enum-like module so valid values are documented in one place."],"exampleFix":"// before\nenv: \"dev\" | \"prod\" = \"production\"\n// after\nenv: \"dev\" | \"prod\" = \"prod\"   // or widen type to include \"production\"","handlingStrategy":"validation","validationCode":"// Pkl\nallowed: List<String> = List(\"dev\", \"staging\", \"prod\")\nif (!allowed.contains(value)) throw(\"\\(value) not in \\(allowed)\")","typeGuard":"function isAllowedEnv(value: Any): Boolean = value is String && List(\"dev\",\"staging\",\"prod\").contains(value)","tryCatchPattern":"// Validate membership in the literal union before assignment; embedders: catch PklException with 'not one of the expected string literals'.","preventionTips":["Mirror literal unions in a type alias and validate external input against it","Extend the union type when introducing new enum-like values","Normalize case/whitespace of inputs from env vars and CLI flags"],"tags":["pkl","type-mismatch","string-literal","enum"],"backgroundTag":"type-mismatch","analyzedSha":"f3efcbfc9b60d30053b0536d664948d7aa1b8673","analyzedAt":"2026-09-08T13:10:45.570Z","contentChangedAt":"2026-09-08T13:10:45.570Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}