Configuración de rango en Shopify: Soluciona el error "Range Parameters Must Have at Most 101 Steps"

El error "Range settings must have at most 101 steps" significa que tu combinación de min, max y step produce más de 101 posiciones posibles en el deslizador. Resuélvelo ampliando step, reduciendo max, o cambiando al tipo de entrada number cuando genuinamente necesites un rango numérico grande. La causa raíz siempre es aritmética, no un error de código.

Puntos clave

• Shopify limita la configuración de rango a un máximo de 101 pasos (validado al momento de cargar el esquema).
• El conteo de pasos se calcula como (max - min) / step; ese resultado debe ser 100 o menos.
• El error aparece en el editor de temas de Shopify y bloquea que la sección se renderice.
• Cambiar step: 1 a un número entero más alto suele ser la solución más rápida.
• Cuando necesites una entrada de entero sin límite, reemplaza range con number.

¿Cuál es la regla de 101 pasos?

El tipo de entrada range de Shopify renderiza un deslizador en el editor de temas. La plataforma impone un límite máximo: el deslizador puede tener como máximo 101 posiciones (pasos 0 a 100, inclusive). Shopify calcula el número de pasos internamente como:

steps = (max - min) / step

Si ese cálculo produce un valor mayor a 100, Shopify rechaza el esquema y lanza:

Error: Invalid schema: setting with id="[your_id]" step invalid.
Range settings must have at most 101 steps.

Esta validación se ejecuta cada vez que el editor de temas carga la sección, por lo que la sección se vuelve completamente no funcional hasta que se corrija el esquema.

Nota: Como confirmó Shopify en su documentación de configuración de entrada, los cuatro atributos de rango (min, max, step, default) deben ser valores numéricos, no cadenas de texto. Pasar una cadena para cualquiera de ellos también genera un error.

Los tres disparadores más comunes

Estos son los patrones que veo con más frecuencia cuando comerciantes o desarrolladores juniors se topan con este problema:

1. Rango grande con step: 1. Establecer min: 0, max: 500, step: 1 crea 500 pasos. Este es el caso más frecuente.
2. Aumentar un max existente sin ajustar el paso. Un desarrollador cambia max de 100 a 300 en un deslizador de ancho de logo, olvidando que el paso permanece en 1.
3. Copiar un rango de un ejemplo de especificación HTML. HTML estándar permite cualquier conteo de pasos; Shopify no.

Los ejemplos reales de la comunidad incluyen un deslizador free_shipping_threshold establecido a min: 0, max: 500, step: 1 y un deslizador logo_max_width aumentado de 300px a 550px sin recalcular el paso.

Cómo calcular si tu rango es válido

Antes de escribir una sola línea de esquema, ejecuta esta verificación:

(max - min) / step <= 100   →  válido
(max - min) / step > 100    →  generará el error de 101 pasos

Ejemplos rápidos

El límite es exactamente 100 pasos calculados (lo que da 101 posiciones en el deslizador incluyendo el punto de inicio). Cualquier valor por encima de 100 es rechazado.

Tres formas de solucionarlo

1. Aumentar el valor del paso

Esta es la solución correcta en la mayoría de los casos. Un deslizador de relleno que va de 0 a 200px en pasos de 2 da a los comerciantes 101 posiciones y se mantiene dentro del límite.

{
  "type": "range",
  "id": "section_padding",
  "label": "Section padding",
  "min": 0,
  "max": 200,
  "step": 2,
  "unit": "px",
  "default": 40
}

Cuándo usarlo: Casi siempre. La mayoría de valores de diseño (relleno, tamaños de fuente, porcentajes de opacidad) no necesitan precisión de unidad única en un rango amplio.

2. Reducir el valor máximo

Si la precisión de un paso es importante (por ejemplo, una calificación de 1 a 5 estrellas o un porcentaje de 0 a 100), simplemente reduce max para mantenerte dentro de 100 pasos con step: 1.

{
  "type": "range",
  "id": "free_shipping_threshold",
  "label": "Free shipping threshold",
  "min": 0,
  "max": 100,
  "step": 1,
  "unit": "$",
  "default": 50
}

Esta solución verificada por la comunidad fue la aceptada para el caso free_shipping_threshold que se extendió por los foros de Shopify.

3. Cambiar al tipo number

Cuando genuinamente necesitas que un comerciante ingrese cualquier entero (un retardo de animación en milisegundos, un conteo de productos mayor a 100, un umbral que podría ser 0-9999), el tipo range no es la herramienta correcta. Usa number en su lugar.

{
  "type": "number",
  "id": "free_shipping_threshold",
  "label": "Free shipping threshold ($)",
  "default": 50
}

El tipo number acepta cualquier entero, no tiene límite de deslizador, y se accede idénticamente en Liquid a través de section.settings.free_shipping_threshold. El compromiso es un campo de texto en lugar de un deslizador, por lo que los comerciantes pueden ingresar valores fuera de rango. Si las barreras son importantes, agrega una verificación en Liquid en tu código de sección.

Elegir la solución correcta: tabla de decisión

Una cosa que muchos tutoriales omiten: range solo admite enteros

La entrada de rango de Shopify no admite valores de paso decimal. Si necesitas un paso de 0.1 para opacidad, la solución es almacenar el valor como entero (0 a 100) y dividir entre 100 en tu salida Liquid:

{% assign opacity = section.settings.overlay_opacity | divided_by: 100.0 %}
<div style="opacity: {{ opacity }}">

Este patrón es más limpio de lo que parece: el comerciante ve un deslizador 0-100, tu CSS obtiene un flotante 0.0-1.0. Sin trucos necesarios.

Verificar tu solución antes de publicar

Theme Check, la herramienta de linting oficial de Shopify, detecta este error durante el desarrollo local. Ejecútalo antes de hacer push de cualquier cambio de esquema:

shopify theme check

Si estás trabajando directamente en el editor de código del administrador de Shopify (sin una configuración de CLI local), guarda el archivo de sección y recarga la vista previa del editor de temas. El error aparece como un banner rojo en la parte superior del personalizador si el esquema aún no es válido.

Para una mirada más profunda a cómo Theme Check maneja la validación de esquema y errores de argumentos, consulta Shopify Theme Check: Por qué un argumento de ruta de archivo único no funciona.

Lista de verificación práctica antes de agregar cualquier configuración de rango

Usa esta lista cada vez que escribas un nuevo bloque range:

• Calcula (max - min) / step y confirma que el resultado es 100 o menos.
• Confirma que los cuatro atributos (min, max, step, default) son enteros, no cadenas de texto.
• Confirma que default cae entre min y max.
• Pregúntate: ¿este valor realmente se beneficia de un deslizador? Si no, usa number, select, o text.
• Prueba en el editor de temas antes de hacer push a producción.

Para un desglose completo de cada tipo de entrada de esquema y cuándo usar cada uno, consulta la guía de desarrollo de temas de Shopify.

Resumen

El error "range parameters must have at most 101 steps" es pura aritmética. La fórmula (max - min) / step debe producir 100 o menos. Amplía tu paso, limita tu max, o cambia al tipo number. Ninguna de estas soluciones requiere una actualización de plan de Shopify, una reinstalación de tema, o un ticket de soporte. Entiende la restricción una vez y nunca volverás a encontrarla.