Stirling-Tools/Stirling-PDF · error · Error

Invalid real-world distance (must be positive)

Error message

Invalid real-world distance (must be positive)

What it means

Thrown by calculateCalibratedScale when realDistance fails Number.isFinite or is <= 0. realDistance is the known real-world length the user enters to calibrate the scale; it is divided by pdfDistancePts, so zero or negative values make the resulting factor meaningless.

Source

Thrown at frontend/editor/src/core/utils/measurementUtils.ts:367

    return null;
  }

  // ratio = factor / baseFactor
  const ratio = factor / baseFactor;
  return Number.isFinite(ratio) && ratio > 0 ? ratio : null;
}

export function calculateCalibratedScale(
  pdfDistancePts: number,
  realDistance: number,
  unit: string,
): MeasureScale {
  if (!Number.isFinite(pdfDistancePts) || pdfDistancePts <= 0) {
    throw new Error("Invalid PDF distance (must be positive)");
  }

  if (!Number.isFinite(realDistance) || realDistance <= 0) {
    throw new Error("Invalid real-world distance (must be positive)");
  }

  const baseFactor = getUnitFactor(unit);
  if (!baseFactor) {
    throw new Error(`Unsupported unit: ${unit}`);
  }

  const factor = realDistance / pdfDistancePts;
  const ratio = deriveRatioFromFactor(factor, unit);

  return {
    factor,
    ratio,
    unit,
  };
}

export function createCalibrationMetadata(

View on GitHub (pinned to 9ef20dcab8)

Solutions

1. Validate the real-distance input is a positive finite number before calling calculateCalibratedScale.
2. Normalize locale separators (replace comma with dot) before parsing.
3. Disable the calibration button until a valid positive number is entered.
4. Show inline field validation with the accepted format.

Example fix

// before
const scale = calculateCalibratedScale(pdfDistancePts, realDistance, unit);

// after
const real = Number(String(realDistance).replace(",", "."));
if (!Number.isFinite(real) || real <= 0) {
  throw new Error("Enter a positive real-world distance (e.g. 10 cm).");
}
const scale = calculateCalibratedScale(pdfDistancePts, real, unit);

const real = Number(String(realDistance).replace(",", "."));
if (!Number.isFinite(real) || real <= 0) {
  throw new Error("Enter a positive real-world distance (e.g. 10 cm).");
}
const scale = calculateCalibratedScale(pdfDistancePts, real, unit);

const isValidRealDistance = (d: unknown): d is number =>
  typeof d === "number" && Number.isFinite(d) && d > 0;

When it happens

Trigger: User submits an empty or '0' real-distance input field; a localized decimal comma ('1,5') parsed with parseFloat yields NaN or a truncated number; copy-paste of whitespace into the field; negative value entered manually.

Common situations: Form field not validated before calibration; locale-specific number formatting breaking parseFloat; default empty string treated as 0.

Related errors

• Invalid scale ratio: ${ratio}
• Unsupported unit: ${unit}
• Invalid PDF distance (must be positive)
• Unexpected trailing input
• One or both documents have no pages.

AI-assisted analysis of Stirling-Tools/Stirling-PDF@9ef20dcab8 (2026-08-13). Data as JSON: /api/errors/3e6a134ffc3ef7a6. Report an issue: GitHub.