apple/pkl · error · FormatException

FormatException("string", obj.getClass())

Error message

FormatException("string", obj.getClass())

What it means

Thrown by PackageUtils.parsePackageUriWithoutChecksums when the input object is not a String. The API expects the raw package URI text; any other type (e.g. a URI object, char sequence of another type, or deserialized non-string) is a format error.

Source

Thrown at pkl-core/src/main/java/org/pkl/core/packages/PackageUtils.java:29

 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.pkl.core.packages;

import java.net.URISyntaxException;
import org.pkl.core.util.ErrorMessages;
import org.pkl.core.util.json.Json.FormatException;
import org.pkl.core.util.json.Json.JsonParseException;

public final class PackageUtils {
  private PackageUtils() {}

  public static PackageUri parsePackageUriWithoutChecksums(Object obj)
      throws JsonParseException, URISyntaxException {
    if (!(obj instanceof String string)) {
      throw new FormatException("string", obj.getClass());
    }
    var packageUri = new PackageUri(string);
    checkHasNoChecksumComponent(packageUri);
    return packageUri;
  }

  public static void checkHasNoChecksumComponent(PackageUri packageUri) throws URISyntaxException {
    if (packageUri.getChecksums() != null) {
      throw new URISyntaxException(
          packageUri.toString(), ErrorMessages.create("unexpectedChecksumInPackageUri"));
    }
  }
}

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Call toString() on URI objects before passing: parsePackageUriWithoutChecksums(uri.toString())
2. Ensure upstream deserialization produces a plain String for the package URI field
3. Check the input with instanceof String before calling

Example fix

// before
var pkg = PackageUtils.parsePackageUriWithoutChecksums(uriObj);
// after
var pkg = PackageUtils.parsePackageUriWithoutChecksums(uriObj.toString());

if (!(input instanceof String s) || s.isBlank()) {
  throw new IllegalArgumentException("Package URI must be a non-empty string");
}

static boolean isStringPackageUri(Object obj) {
  return obj instanceof String s && s.startsWith("package://");
}

if (!(obj instanceof String string)) {
  throw new IllegalArgumentException("Expected a String package URI, got: " + obj.getClass());
}
var pkg = PackageUtils.parsePackageUriWithoutChecksums(string);

When it happens

Trigger: Calling parsePackageUriWithoutChecksums(obj) where obj is not an instanceof String — e.g. passing java.net.URI, a GString-like wrapper, or JSON-decoded non-string values.

Common situations: Deserialized configuration where the package URI field came back as a non-string; passing a URI instance instead of uri.toString(); generic pipelines that forward unchecked values.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

• Error converting property `%s` in Pkl object of type `%s` to
• The top-level value of a YAML stream must have type `Collect
• type constraint mismatch
• type mismatch
• type mismatch (Nothing type)

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