apple/pkl · error · VmException

intTooLarge

intTooLarge

Error message

intTooLarge

What it means

Pkl integer literals must fit in a signed 64-bit (Long) value. When `parseInt` fails via `Long::parseLong` throwing NumberFormatException, the builder reports that the integer is too large rather than silently truncating or promoting to Float.

Source

Thrown at pkl-core/src/main/java/org/pkl/core/ast/builder/AstBuilder.java:711

    // relies on grammar rule nesting depth, but a breakage won't go unnoticed by tests
    if (expr.parent() instanceof UnaryMinusExpr) {
      // handle negation here to make parsing of base.MinInt work
      // also moves negation from runtime to parse time
      text = "-" + text;
    }
    return parser.apply(text, radix);
  }

  @Override
  public IntLiteralNode visitIntLiteralExpr(IntLiteralExpr expr) {
    var section = createSourceSection(expr);
    try {
      var num = parseInt(expr, Long::parseLong);
      return new IntLiteralNode(section, num);
    } catch (NumberFormatException e) {
      var text = expr.getNumber();
      throw exceptionBuilder().evalError("intTooLarge", text).withSourceSection(section).build();
    }
  }

  @Override
  public FloatLiteralNode visitFloatLiteralExpr(FloatLiteralExpr expr) {
    var section = createSourceSection(expr);
    var text = VmUtils.removeUnderscoresFromNumber(expr.getNumber(), true);
    // relies on grammar rule nesting depth, but a breakage won't go unnoticed by tests
    if (expr.parent() instanceof UnaryMinusExpr) {
      // handle negation here for consistency with visitIntegerLiteral
      // also moves negation from runtime to parse time
      text = "-" + text;
    }

    try {
      var num = Double.parseDouble(text);
      return new FloatLiteralNode(section, num);
    } catch (NumberFormatException e) {

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Reduce the literal to within the signed 64-bit range.
2. Write the value as a Float literal (append `.0`) if approximate precision suffices.
3. Encode the value as a String and parse it in code outside Pkl, or split into components.

Example fix

// before
x = 12345678901234567890123
// after
x: Float = 1.2345678901234568e22

// Guard before emitting a Pkl Int literal (JS example):
function withinInt64(n) {
  return Number.isInteger(n) && n >= -(2n**63n) && n <= 2n**63n - 1n;
}

const isPklInt = (v: bigint | number): boolean =>
  typeof v === 'bigint'
    ? v >= -(2n ** 63n) && v <= 2n ** 63n - 1n
    : Number.isSafeInteger(v);

try {
  renderPklConfig(cfg);
} catch (e) {
  if (String(e).includes('intTooLarge')) {
    // downgrade to Float or String representation
  }
}

When it happens

Trigger: Writing an Int literal whose magnitude exceeds Long.MIN_VALUE..Long.MAX_VALUE (about 9.2 * 10^18), e.g. `x = 99999999999999999999`.

Common situations: Pasting large constants (IDs, hashes, seconds-since-epoch in nanoseconds) from other languages that use arbitrary-precision or unsigned 64-bit integers.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• `%s` is too large to fit into a Version.
• floatTooLarge
• cannotConvertToIsoDuration
• cannotConvertLargeFloat
• invalidCodePoint

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