apple/pkl · error · NoSuchChildException

Node `%s` of type `%s` does not have a key named `%s`. Avail

Error message

Node `%s` of type `%s` does not have a key named `%s`. Available keys: %s

What it means

MapConfig wraps a Pkl Map. getRawChildValue looks up the requested key in the map and, when absent (null), throws NoSuchChildException listing the node name, the Pkl Map type, the requested key, and the keys that exist. Unlike a composite's properties, missing keys here are simply absent entries in the map.

Source

Thrown at pkl-config-java/src/main/java/org/pkl/config/java/MapConfig.java:40

class MapConfig extends AbstractConfig {
  private final Map<?, ?> map;

  MapConfig(String qualifiedName, ValueMapper mapper, Map<?, ?> map) {
    super(qualifiedName, mapper);
    this.map = map;
  }

  @Override
  public Object getRawValue() {
    return map;
  }

  @Override
  protected Object getRawChildValue(String propertyName) {
    var result = map.get(propertyName);
    if (result != null) return result;

    throw new NoSuchChildException(
        String.format(
            "Node `%s` of type `%s` does not have a key named `%s`. Available keys: %s",
            getQualifiedName(), PClassInfo.Map.getQualifiedName(), propertyName, map.keySet()),
        propertyName);
  }
}

View on GitHub (pinned to f3efcbfc9b)

Solutions

Correct the key using the 'Available keys' list printed in the exception.
Check the .pkl source to confirm the key exists and its exact spelling/casing.
Use a nullable/optional map lookup (map.get returns null check) when absence is expected.
Add the missing key to the Pkl map if the entry is genuinely required for this environment.

Example fix

// before
var region = mapConfig.getChild("eu-west-3"); // not in map
// after
if (mapConfig.getRawChildValue("eu-west-1") == null) {
  region = DEFAULT_REGION;
} else {
  region = mapConfig.getChild("eu-west-1");
}

Defensive patterns

Strategy: validation

Validate before calling

// verify the key exists on the map config before access
var keys = mapConfig.getRawChildNames(); // or inspect the Pkl map's keySet
if (!keys.contains(key)) {
  throw new IllegalArgumentException(key + " not in " + keys);
}

Type guard

static boolean hasKey(MapConfig map, String key) {
  try { map.getRawChildValue(key); return true; }
  catch (NoSuchChildException e) { return false; }
}

Try / catch

try {
  return mapConfig.getChild(key);
} catch (NoSuchChildException e) {
  log.warn("map config missing key {} (available: {})", key, e.getAvailableKeys());
  return Optional.empty();
}

Prevention

Copy map keys exactly as declared in the .pkl source (watch case and dashes)
For optional entries, use nullable lookups instead of getChild
Add Pkl-level validation to require environment-critical keys
Treat 'Available keys' output as a diff against what your code expects

When it happens

Trigger: Accessing config children keyed by map keys (e.g. config.get("myMap").get("missingKey")) where the key string is not present in the Pkl map's keySet.

Common situations: Case or spelling mismatch between Java code and keys declared in the .pkl map; environment-specific entries (e.g. per-region keys) missing from a config file; keys computed dynamically (IDs, hostnames) that don't exist for the current environment.

Related errors

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