{"record":{"id":"63e1bad0ed85674b","repo":"oracle/graal","slug":"unrecognized-vm-option","errorCode":null,"errorMessage":"Unrecognized VM option: '","messagePattern":"Unrecognized VM option: '","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"espresso-compiler-stub/src/com.oracle.truffle.espresso.vmaccess/src/com/oracle/truffle/espresso/vmaccess/EspressoExternalVMAccessBuilder.java","lineNumber":218,"sourceCode":"                }\n                return;\n            } else if (\"log.file\".equals(key)) {\n                OutputStream out;\n                try {\n                    out = new BufferedOutputStream(Files.newOutputStream(Paths.get(value), StandardOpenOption.WRITE, StandardOpenOption.CREATE, StandardOpenOption.APPEND));\n                } catch (IOException e) {\n                    throw new IllegalArgumentException(\"Cannot use the specified log.file\", e);\n                }\n                builder.logHandler(out);\n                return;\n            }\n        }\n        OptionDescriptor descriptor = findOptionDescriptor(group, key);\n        if (descriptor == null) {\n            key = JAVA_LANGUAGE_ID + \".\" + key;\n            descriptor = findOptionDescriptor(JAVA_LANGUAGE_ID, key);\n            if (descriptor == null) {\n                throw new IllegalArgumentException(\"Unrecognized VM option: '\" + vmOption);\n            }\n        }\n        try {\n            descriptor.getKey().getType().convert(value);\n        } catch (IllegalArgumentException e) {\n            throw new IllegalArgumentException(String.format(\"Invalid VM option %s specified. %s\", vmOption, e.getMessage()));\n        }\n        builder.option(key, value);\n    }\n\n    private static OptionDescriptor findOptionDescriptor(String group, String key) {\n        OptionDescriptors descriptors = null;\n        switch (group) {\n            case \"engine\":\n            case \"compiler\":\n                descriptors = getTempEngine().getOptions();\n                break;\n            default:","sourceCodeStart":200,"sourceCodeEnd":236,"githubUrl":"https://github.com/oracle/graal/blob/a66e9ccd1d7bf2552883939aa0788dfd0e294aab/espresso-compiler-stub/src/com.oracle.truffle.espresso.vmaccess/src/com/oracle/truffle/espresso/vmaccess/EspressoExternalVMAccessBuilder.java#L200-L236","documentation":"Thrown by EspressoExternalVMAccessBuilder when a VM option key cannot be matched to any known option descriptor. The builder looks up the key in the engine, compiler, and Espresso ('java') option groups; if no group knows the key (after also trying the 'java.'-prefixed form), it is rejected as unrecognized.","triggerScenarios":"Passing a misspelled or nonexistent option key to the builder (e.g. 'java.Continue' instead of 'java.ContinueOnInitializationError'), passing a plain-engine option without the right group prefix, or passing a HotSpot-only -XX/-H: flag that Espresso does not define.","commonSituations":"Typos in option names; using options that only exist in a different GraalVM/Espo version after an upgrade; copy-pasting substratevm (native-image) options into an Espresso embedder; dropping the 'java.' prefix for Espresso-specific options.","solutions":["Fix the spelling/prefix of the option: Espresso options need the 'java.' group (builder also tries the prefixed form automatically), engine options 'engine.*', compiler options 'compiler.*'","Enumerate valid keys from the engine's OptionDescriptors (getTempEngine().getOptions() / language options) and diff them against what you pass","After upgrading GraalVM, re-check that the option still exists; guard version-specific options behind a capability check"],"exampleFix":"// before\nbuilder.option(\"java.Continue\", \"true\"); // typo: option does not exist\n\n// after\nbuilder.option(\"java.ContinueOnInitializationError\", \"true\");","handlingStrategy":"validation","validationCode":"OptionDescriptors known = engine.getOptions(); // plus language 'java' options\nif (known.get(key) == null) throw new IllegalArgumentException(\"Unknown option, available: \" + known);","typeGuard":null,"tryCatchPattern":"catch (IllegalArgumentException e) { print available option keys near the failure to help fix the typo }","preventionTips":["Centralize all VM option strings as named constants instead of scattering string literals","After a GraalVM upgrade, diff your option list against the new OptionDescriptors"],"tags":["espresso","configuration","vm-options","validation"],"backgroundTag":null,"analyzedSha":"a66e9ccd1d7bf2552883939aa0788dfd0e294aab","analyzedAt":"2026-08-14T13:58:47.161Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}