arduino/Arduino · error · PreferencesMapException

throw new PreferencesMapException(k)

Error message

throw new PreferencesMapException(k)

What it means

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.

Source

Thrown at arduino-core/src/processing/app/helpers/PreferencesMap.java:268

    for (String k : treeSet)
      res += indent + "  " + k + " = " + get(k) + "\n";
    res += indent + "}\n";
    return res;
  }

  /**
   * Returns the value to which the specified key is mapped, or throws a
   * PreferencesMapException if not found
   * 
   * @param k
   *          the key whose associated value is to be returned
   * @return the value to which the specified key is mapped
   * @throws PreferencesMapException
   */
  public String getOrExcept(String k) throws PreferencesMapException {
    String r = get(k);
    if (r == null)
      throw new PreferencesMapException(k);
    return r;
  }

  @Override
  public String toString() {
    return toString("");
  }

  /**
   * Creates a new File instance by converting the value of the key into an
   * abstract pathname. If the the given key doesn't exists or his value is the
   * empty string, the result is <b>null</b>.
   * 
   * @param key
   * @return
   */
  public File getFile(String key) {
    if (!containsKey(key))

View on GitHub (pinned to a0df6e0e83)

Solutions

1. Add the reported key to the appropriate boards.txt/platform.txt/programmers.txt entry
2. Install the missing tool/core so runtime.tools.<key> paths get populated (Boards Manager)
3. Select the correct board in Tools > Board so the right preference set is loaded
4. Search the key name (the exception message) across the hardware folder to find which file must define it

Example fix

// before
String mcu = prefs.getOrExcept("build.mcu"); // throws if absent
// after
String mcu = prefs.get("build.mcu");
if (mcu == null) {
  throw new IllegalStateException("build.mcu missing; check boards.txt for " + prefs.get("name"));
}

String mcu = prefs.get("build.mcu");
if (mcu == null) throw new IllegalStateException("build.mcu not defined; check boards.txt/platform.txt");

try {
  String v = prefs.getOrExcept(key);
} catch (PreferencesMapException e) {
  logger.error("Required property missing: " + e.getMessage());
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• throw new PreferencesMapException(key)
• 'Invalid quoting: no closing [' + escapingChar + '] char fou
• KeyError(key)

AI-assisted analysis of arduino/Arduino@a0df6e0e83 (2026-09-06). Data as JSON: /api/errors/497d265c0c50d3eb. Report an issue: GitHub.