{"record":{"id":"497d265c0c50d3eb","repo":"arduino/Arduino","slug":"throw-new-preferencesmapexception-k","errorCode":null,"errorMessage":"throw new PreferencesMapException(k)","messagePattern":"throw new PreferencesMapException\\(k\\)","errorType":"exception","errorClass":"PreferencesMapException","httpStatus":null,"severity":"error","filePath":"arduino-core/src/processing/app/helpers/PreferencesMap.java","lineNumber":268,"sourceCode":"    for (String k : treeSet)\n      res += indent + \"  \" + k + \" = \" + get(k) + \"\\n\";\n    res += indent + \"}\\n\";\n    return res;\n  }\n\n  /**\n   * Returns the value to which the specified key is mapped, or throws a\n   * PreferencesMapException if not found\n   * \n   * @param k\n   *          the key whose associated value is to be returned\n   * @return the value to which the specified key is mapped\n   * @throws PreferencesMapException\n   */\n  public String getOrExcept(String k) throws PreferencesMapException {\n    String r = get(k);\n    if (r == null)\n      throw new PreferencesMapException(k);\n    return r;\n  }\n\n  @Override\n  public String toString() {\n    return toString(\"\");\n  }\n\n  /**\n   * Creates a new File instance by converting the value of the key into an\n   * abstract pathname. If the the given key doesn't exists or his value is the\n   * empty string, the result is <b>null</b>.\n   * \n   * @param key\n   * @return\n   */\n  public File getFile(String key) {\n    if (!containsKey(key))","sourceCodeStart":250,"sourceCodeEnd":286,"githubUrl":"https://github.com/arduino/Arduino/blob/a0df6e0e83b652c72bc78b0a1376c54d6ebc3bee/arduino-core/src/processing/app/helpers/PreferencesMap.java#L250-L286","documentation":"PreferencesMap.getOrExcept(k) returns the mapped value or throws PreferencesMapException carrying the missing key when the key is absent. Unlike get(), it treats the key as mandatory, used for required build properties (e.g. upload.port, build.path, tool paths) during compile/upload flows. The exception message is just the key name, so look for that token in your config files.","triggerScenarios":"Calling getOrExcept on a PreferencesMap that lacks the key — e.g. upload/tool recipes calling prefs.getOrExcept(\"runtime.tools.<tool>.path\") or board properties missing required fields like build.mcu when boards.txt/platform.txt is incomplete.","commonSituations":"Missing or wrong board selected with incomplete platform installation; missing tool entries because runtime.tools.* were never populated (tool not installed); hand-trimmed boards.txt/platform.txt removing a required key; third-party platform missing recipe variables.","solutions":["Add the reported key to the appropriate boards.txt/platform.txt/programmers.txt entry","Install the missing tool/core so runtime.tools.<key> paths get populated (Boards Manager)","Select the correct board in Tools > Board so the right preference set is loaded","Search the key name (the exception message) across the hardware folder to find which file must define it"],"exampleFix":"// before\nString mcu = prefs.getOrExcept(\"build.mcu\"); // throws if absent\n// after\nString mcu = prefs.get(\"build.mcu\");\nif (mcu == null) {\n  throw new IllegalStateException(\"build.mcu missing; check boards.txt for \" + prefs.get(\"name\"));\n}","handlingStrategy":"try-catch","validationCode":"String mcu = prefs.get(\"build.mcu\");\nif (mcu == null) throw new IllegalStateException(\"build.mcu not defined; check boards.txt/platform.txt\");","typeGuard":null,"tryCatchPattern":"try {\n  String v = prefs.getOrExcept(key);\n} catch (PreferencesMapException e) {\n  logger.error(\"Required property missing: \" + e.getMessage());\n}","preventionTips":["Grep the exception's key name across hardware folders before changing configs","Install all tools required by the selected board via Boards Manager","Select the right board before compiling/uploading","Don't trim 'unused' keys from boards.txt/platform.txt"],"tags":["preferences","missing-key","arduino-build","config"],"backgroundTag":"missing-config-key","analyzedSha":"a0df6e0e83b652c72bc78b0a1376c54d6ebc3bee","analyzedAt":"2026-09-06T10:13:38.901Z","contentChangedAt":"2026-09-06T10:13:38.901Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}