Shopify Range-Einstellung: Behebe den "101 Schritte"-Fehler

Der Fehler "Range settings must have at most 101 steps" bedeutet, dass deine Kombination aus min, max und step mehr als 101 mögliche Schieberegler-Positionen erzeugt. Behebe ihn, indem du step vergrößerst, max verkleinerst oder zum Input-Typ number wechselst, wenn du wirklich einen großen numerischen Bereich brauchst. Die Ursache ist immer Mathematik, nie ein Bug.

Wichtigste Erkenntnisse

• Shopify begrenzt Range-Einstellungen auf maximal 101 Schritte (erzwungen beim Schema-Parsen).
• Die Schrittanzahl wird berechnet als (max - min) / step; dieses Ergebnis muss 100 oder weniger sein.
• Der Fehler erscheint im Shopify Theme-Editor und blockiert das Rendering des Bereichs.
• Das Ändern von step: 1 auf eine höhere ganze Zahl ist meist der schnellste Fix.
• Wenn du eine unbegrenzte Integer-Eingabe brauchst, ersetze range durch number.

Was ist die 101-Schritte-Regel?

Der range Input-Typ von Shopify rendert einen Schieberegler im Theme-Editor. Die Plattform erzwingt eine harte Obergrenze: der Schieberegler kann höchstens 101 Positionen haben (Schritte 0 bis 100, einschließlich). Shopify berechnet die Anzahl der Schritte intern als:

steps = (max - min) / step

Wenn diese Berechnung einen Wert größer als 100 ergibt, lehnt Shopify das Schema ab und wirft:

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

Diese Validierung läuft jedes Mal aus, wenn der Theme-Editor den Bereich laden, daher wird der Bereich völlig funktionsunfähig, bis das Schema korrigiert ist.

Hinweis: Wie Shopify in ihrer Dokumentation zu Input-Einstellungen bestätigt hat, müssen alle vier Range-Attribute (min, max, step, default) numerische Werte sein, keine Strings. Die Übergabe eines Strings für eines davon wirft ebenfalls einen Fehler.

Die drei häufigsten Auslöser

Dies sind die Muster, die ich am häufigsten sehe, wenn Händler oder Junior-Entwickler auf diese Hürde stoßen:

1. Großer Bereich mit step: 1, Das Setzen von min: 0, max: 500, step: 1 erzeugt 500 Schritte. Das ist der häufigste Fall.
2. Erhöhung eines bestehenden max ohne Anpassung des step, Ein Entwickler ändert max von 100 auf 300 bei einem Logo-Breiten-Schieberegler und vergisst, dass step bei 1 bleibt.
3. Kopieren eines Range aus einer HTML-Spezifikations-Beispiel, Der Standard-HTML erlaubt beliebige Schrittanzahlen; Shopify nicht.

Echte Community-Beispiele umfassen einen free_shipping_threshold Schieberegler mit min: 0, max: 500, step: 1 und einen logo_max_width Schieberegler, der von 300px auf 550px erhöht wurde, ohne den Schritt neu zu berechnen.

So berechnest du, ob dein Range gültig ist

Bevor du eine einzige Zeile Schema schreibst, führe diese Prüfung durch:

(max - min) / step <= 100   →  gültig
(max - min) / step > 100    →  wirft den 101-Schritte-Fehler

Schnelle Beispiele

Die Grenze liegt genau bei 100 berechneten Schritten (was 101 Schieberegler-Positionen einschließlich des Startpunkts ergibt). Jeder Wert über 100 wird abgelehnt.

Drei Wege zum Beheben

1. Erhöhe den Step-Wert

Dies ist in den meisten Fällen die richtige Lösung. Ein Padding-Schieberegler, der von 0 bis 200px in Schritten von 2 geht, bietet Händlern 101 Positionen und bleibt innerhalb der Grenze.

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

Wann nutzen: Fast immer. Die meisten Design-Werte (Padding, Schriftgrößen, Deckkraft-Prozentsätze) benötigen keine Einzelschritt-Genauigkeit über einen großen Bereich.

2. Reduziere den Max-Wert

Wenn die Genauigkeit eines einzelnen Schritts wichtig ist (z.B. eine 1-bis-5-Sterne-Bewertung oder ein 0-bis-100-Prozentsatz), reduziere einfach max, um bei step: 1 innerhalb von 100 Schritten zu bleiben.

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

Dieser von der Community bestätigte Fix war die akzeptierte Lösung für den free_shipping_threshold Fall, der sich über die Shopify-Foren verbreitete.

3. Wechsel zum number Typ

Wenn du wirklich brauchst, dass ein Händler eine beliebige ganze Zahl eingeben kann (eine Animationsverzögerung in Millisekunden, eine Produktanzahl über 100, eine Schwelle, die 0-9999 sein könnte), ist der range Typ das komplett falsche Werkzeug. Nutze stattdessen number.

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

Der number Typ akzeptiert jede ganze Zahl, hat keine Schieberegler-Obergrenze und wird in Liquid identisch aufgerufen via section.settings.free_shipping_threshold. Der Nachteil ist ein Texteingabefeld statt eines Schiebereglers, damit Händler Werte außerhalb des Bereichs eingeben können. Wenn Grenzen wichtig sind, füge eine Liquid-Prüfung in deinem Bereichs-Code hinzu.

Die richtige Lösung wählen: eine Entscheidungstabelle

Eine Sache, die viele Tutorials überspringen: Range unterstützt nur ganze Zahlen

Shopifys Range Input unterstützt keine dezimalen Step-Werte. Wenn du einen 0.1 Step für Deckkraft brauchst, ist die Lösung, den Wert als ganze Zahl (0 bis 100) zu speichern und in deiner Liquid-Ausgabe durch 100 zu teilen:

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

Dieses Muster ist sauberer als es aussieht: der Händler sieht einen 0-100 Schieberegler, dein CSS bekommt einen 0.0-1.0 Float. Keine Hacks nötig.

Deinen Fix vor Veröffentlichung überprüfen

Theme Check, Shopifys offizielle Linting-CLI, findet diesen Fehler während der lokalen Entwicklung. Nutze sie vor dem Pushen von Schema-Änderungen:

shopify theme check

Wenn du direkt im Shopify Admin Code-Editor arbeitest (ohne lokales CLI-Setup), speichere die Bereichs-Datei und laden den Theme-Editor Vorschau neu. Der Fehler erscheint als rotes Banner oben im Customizer, wenn das Schema immer noch ungültig ist.

Für einen tieferen Blick auf die Art, wie Theme Check Schema-Validierung und Argument-Fehler handhabt, siehe Shopify Theme Check: Warum ein Single-File-Path-Argument nicht funktioniert.

Praktische Checkliste vor dem Hinzufügen einer Range-Einstellung

Nutze diese Liste jedes Mal, wenn du einen neuen range Block schreibst:

• Berechne (max - min) / step und bestätige, dass das Ergebnis 100 oder darunter liegt.
• Bestätige, dass alle vier Attribute (min, max, step, default) ganze Zahlen sind, keine Strings.
• Bestätige, dass default zwischen min und max liegt.
• Frage dich: profitiert dieser Wert wirklich von einem Schieberegler? Falls nicht, nutze number, select oder text.
• Teste im Theme-Editor, bevor du in die Produktion pushst.

Für eine vollständige Aufschlüsselung aller Schema Input-Typen und wann du zu jedem greifen solltest, siehe den Shopify Theme Development Leitfaden.

Zusammenfassung

Der Fehler "range parameters must have at most 101 steps" ist reine Mathematik. Die Formel (max - min) / step muss 100 oder weniger ergeben. Vergrößere deinen Step, begrenze dein Max oder wechsel zum number Typ. Keiner dieser Fixes benötigt ein Shopify Plan Upgrade, eine Theme-Neuinstallation oder ein Support-Ticket. Verstehe die Einschränkung einmal und du wirst sie nie wieder treffen.