apple/pkl · error · VmException

invalidSettingsFile

invalidSettingsFile

Error message

invalidSettingsFile

What it means

PklSettings files (`pklSettings.pkl`) must define an `editor` object containing a non-null string `urlScheme` property. When parseSettings loads the settings module and either `editor` is missing/not an object or `editor.urlScheme` is not a String, it rejects the whole settings file as invalid. This guards against malformed or outdated pklSettings.pkl files that the CLI cannot interpret.

Source

Thrown at pkl-core/src/main/java/org/pkl/core/settings/PklSettings.java:113

                SecurityManagers.standard(
                    ALLOWED_MODULES, ALLOWED_RESOURCES, SecurityManagers.defaultTrustLevels, null))
            .setStackFrameTransformer(StackFrameTransformers.defaultTransformer)
            .addModuleKeyFactory(ModuleKeyFactories.standardLibrary)
            .addModuleKeyFactory(ModuleKeyFactories.file)
            .addResourceReader(ResourceReaders.environmentVariable())
            .addEnvironmentVariables(System.getenv())
            .build()) {
      var module = evaluator.evaluateOutputValueAs(moduleSource, PClassInfo.Settings);
      return parseSettings(module, moduleSource);
    }
  }

  private static PklSettings parseSettings(PObject module, ModuleSource location)
      throws VmEvalException {

    if (!(module.getPropertyOrNull("editor") instanceof PObject pObject)
        || !(pObject.getPropertyOrNull("urlScheme") instanceof String str)) {
      throw new VmExceptionBuilder().evalError("invalidSettingsFile", location.getUri()).build();
    }
    var editor = new Editor(str);
    var httpSettings = PklEvaluatorSettings.Http.parse((Value) module.getProperty("http"));
    return new PklSettings(editor, httpSettings);
  }

  /**
   * Returns the editor for viewing and editing Pkl files.
   *
   * <p>This method is deprecated, use {@link #editor()} instead.
   */
  @Deprecated(forRemoval = true)
  public Editor getEditor() {
    return editor;
  }

  /** An editor for viewing and editing Pkl files. */
  public record Editor(String urlScheme) {

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Add the required editor block: `editor { urlScheme = "vscode" }` (or your editor's scheme) to pklSettings.pkl.
2. Check spelling/casing of `editor` and `urlScheme` properties.
3. Ensure urlScheme is a String literal, not null, a number, or an expression evaluating to a non-string.
4. Regenerate or update pklSettings.pkl from the current Pkl version's documented template.

Example fix

// before (pklSettings.pkl)
http {
  proxies = new {}
}

// after
editor {
  urlScheme = "vscode"
}
http {
  proxies = new {}
}

// pklSettings.pkl self-check
if (editor?.urlScheme is String == false) {
  throw("pklSettings.pkl must define editor { urlScheme = <String> }")
}

function isValidSettings(m) { return m?.editor instanceof Object && typeof m.editor?.urlScheme === 'string'; }

try { loadSettings(path) } catch (e: VmEvalException) { if (e.message.contains('invalidSettingsFile')) regenerateDefaults(path) else throw e }

When it happens

Trigger: Loading a pklSettings.pkl via load() where the module has no `editor` property, `editor` is not a PObject, `editor.urlScheme` is absent, or `editor.urlScheme` is not a String.

Common situations: Hand-edited or generated pklSettings.pkl missing the editor block; copying an old settings file from a Pkl version with a different schema; a typo like `urlScheem = "..."`; setting urlScheme to a non-string (e.g. null or a number).

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• No security manager set.
• invalidUri
• externalReaderDoesNotSupportScheme
• expectedNonEmptyCollection
• expectedSingleElementCollection

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