Errors reference

Diagnostics are generated from the catalogs used by validation, rendering, interaction, and the CLI. Identity is the pair (source, code): a bare code can intentionally exist in more than one source with a different consequence.

Quickstart troubleshooting

• Collapsed or zero-width container: the responsive plot remains data-gg-ready="false" until ResizeObserver reports a positive width. Give the parent a real grid/flex track width; no fixed chart width is needed.
• SSR and hydration: omitted width server-renders at 832 × 400, stays not-ready on the server, then measures its real container after hydration.
• Unexpected height: omitted height is 400px unless the spec supplies one.
• TypeScript or linked-package mismatch: install one compatible @ggsvelte/svelte version and let it resolve matching core/spec packages; remove stale lockfile overrides that mix versions.
• CLI input failure: run ggsvelte-render --help; keep SVG stdout separate from JSON Lines stderr while correcting the reported input.

Validation errors (@ggsvelte/spec)

Each entry answers what failed, why, how to recover safely, and whether output was blocked or degraded.

invalid-spec-root

Code + severity: invalid-spec-root · error

What failed: Spec validation rejected the value at its reported path (schema shape).

Why: The spec is not a JSON object.

Fix: Provide an object with at least one layer: {"layers": [{"geom": "point", ...}]}.

Consequence (blocked): Validation failed; no chart should be rendered from this spec.

Stable link: /guide/errors#invalid-spec-root

missing-layers

Code + severity: missing-layers · error

What failed: Spec validation rejected the value at its reported path (schema shape).

Why: layers is missing or not an array.

Fix: Add a layers array with at least one layer object.

Consequence (blocked): Validation failed; no chart should be rendered from this spec.

Stable link: /guide/errors#missing-layers

empty-layers

Code + severity: empty-layers · error

What failed: Spec validation rejected the value at its reported path (schema shape).

Why: layers is present but empty (a plot needs at least one layer).

Fix: Add a layer, e.g. {"geom": "point"}.

Consequence (blocked): Validation failed; no chart should be rendered from this spec.

Stable link: /guide/errors#empty-layers

invalid-layer

Code + severity: invalid-layer · error

What failed: Spec validation rejected the value at its reported path (schema shape).

Why: A layer is not an object.

Fix: Replace the entry with a layer object carrying a "geom".

Consequence (blocked): Validation failed; no chart should be rendered from this spec.

Stable link: /guide/errors#invalid-layer

missing-geom

Code + severity: missing-geom · error

What failed: Spec validation rejected the value at its reported path (schema shape).

Why: A layer has no "geom" discriminator.

Fix: Add a geom name to the layer, e.g. {"geom": "point"}.

Consequence (blocked): Validation failed; no chart should be rendered from this spec.

Stable link: /guide/errors#missing-geom

unknown-geom

Code + severity: unknown-geom · error

What failed: Spec validation rejected the value at its reported path (schema shape).

Why: A layer's "geom" is not a known geom name.

Fix: Use one of the allowed geoms (the error lists them, with a did-you-mean).

Consequence (blocked): Validation failed; no chart should be rendered from this spec.

Stable link: /guide/errors#unknown-geom

invalid-channel-value

Code + severity: invalid-channel-value · error

What failed: Spec validation rejected the value at its reported path (schema shape).

Why: A channel value is not one of the canonical forms {field}/{value}/{stat}/null (bare strings are builder-only shorthand).

Fix: Wrap field mappings as {"field": "column_name"} and constants as {"value": ...}.

Consequence (blocked): Validation failed; no chart should be rendered from this spec.

Stable link: /guide/errors#invalid-channel-value

unexpected-property

Code + severity: unexpected-property · error

What failed: Spec validation rejected the value at its reported path (schema shape).

Why: An object carries a property the schema does not allow.

Fix: Remove or rename the property (the error suggests the closest allowed name).

Consequence (blocked): Validation failed; no chart should be rendered from this spec.

Stable link: /guide/errors#unexpected-property

missing-property

Code + severity: missing-property · error

What failed: Spec validation rejected the value at its reported path (schema shape).

Why: A required property is missing.

Fix: Add the named property.

Consequence (blocked): Validation failed; no chart should be rendered from this spec.

Stable link: /guide/errors#missing-property

invalid-enum-value

Code + severity: invalid-enum-value · error

What failed: Spec validation rejected the value at its reported path (schema shape).

Why: A value is outside its declared enum/literal set.

Fix: Use one of the allowed values (the error lists them, with a did-you-mean).

Consequence (blocked): Validation failed; no chart should be rendered from this spec.

Stable link: /guide/errors#invalid-enum-value

value-out-of-range

Code + severity: value-out-of-range · error

What failed: Spec validation rejected the value at its reported path (schema shape).

Why: A numeric value is outside its declared bounds.

Fix: Set the value inside the bounds stated by the error message.

Consequence (blocked): Validation failed; no chart should be rendered from this spec.

Stable link: /guide/errors#value-out-of-range

invalid-data

Code + severity: invalid-data · error

What failed: Spec validation rejected the value at its reported path (schema shape).

Why: data (or a dataset entry) matches none of the data forms.

Fix: Use {"values": [...rows]}, {"columns": {...arrays}}, or {"name": "dataset"}.

Consequence (blocked): Validation failed; no chart should be rendered from this spec.

Stable link: /guide/errors#invalid-data

invalid-type

Code + severity: invalid-type · error

What failed: Spec validation rejected the value at its reported path (schema shape).

Why: Fallback: a value has the wrong JSON type.

Fix: Give the property the JSON type the message names.

Consequence (blocked): Validation failed; no chart should be rendered from this spec.

Stable link: /guide/errors#invalid-type

scale-scheme-type

Code + severity: scale-scheme-type · error

What failed: Spec validation rejected the value at its reported path (schema shape).

Why: A named color scheme is incompatible with the configured color scale type.

Fix: Use a categorical scheme with "ordinal" (or a sequential-family scheme like "viridis" for discrete viridis), or "viridis"/hex stops with "sequential".

Consequence (blocked): Validation failed; no chart should be rendered from this spec.

Stable link: /guide/errors#scale-scheme-type

scale-range-color

Code + severity: scale-range-color · error

What failed: Spec validation rejected the value at its reported path (schema shape).

Why: A custom color range contains a color outside the supported hex syntax.

Fix: Replace each custom color with #rgb or #rrggbb syntax.

Consequence (blocked): Validation failed; no chart should be rendered from this spec.

Stable link: /guide/errors#scale-range-color

scale-type-transform-conflict

Code + severity: scale-type-transform-conflict · error

What failed: Spec validation rejected the value at its reported path (schema shape).

Why: A scale declares an incompatible type/family with its transform (temporal/discrete/manual/identity with a non-identity transform, or type: "log" with a non-log10 transform).

Fix: Use identity for temporal/discrete/manual/identity scales; for base-10 log use type: "linear" with transform: "log10"; or choose a quantitative family that admits the transform.

Consequence (blocked): Validation failed; no chart should be rendered from this spec.

Stable link: /guide/errors#scale-type-transform-conflict

color-manual-domain-range

Code + severity: color-manual-domain-range · error

What failed: Spec validation rejected the value at its reported path (schema shape).

Why: A manual color/fill scale has a different number of domain values and range colors.

Fix: Provide exactly one range color for every domain value.

Consequence (blocked): Validation failed; no chart should be rendered from this spec.

Stable link: /guide/errors#color-manual-domain-range

scale-binned-breaks

Code + severity: scale-binned-breaks · error

What failed: Spec validation rejected the value at its reported path (schema shape).

Why: A binned style scale's authored breaks are missing, non-finite after parsing, duplicated, or not strictly increasing.

Fix: Provide 2+ strictly increasing boundaries (numeric, or temporal strings that parse under the scale's parser).

Consequence (blocked): Validation failed; no chart should be rendered from this spec.

Stable link: /guide/errors#scale-binned-breaks

scale-binned-domain

Code + severity: scale-binned-domain · error

What failed: Spec validation rejected the value at its reported path (schema shape).

Why: A binned style scale's explicit domain does not match the first and last authored breaks.

Fix: Set domain to the first and last break values, or omit domain and let breaks define it.

Consequence (blocked): Validation failed; no chart should be rendered from this spec.

Stable link: /guide/errors#scale-binned-domain

guide-aesthetic-incompatible

Code + severity: guide-aesthetic-incompatible · error

What failed: Spec validation rejected the value at its reported path (schema shape).

Why: A guide variant is incompatible with its aesthetic or trained scale family.

Fix: Use axis for x/y, legend for discrete/style scales, colorbar for sequential color, or colorsteps for binned color.

Consequence (blocked): Validation failed; no chart should be rendered from this spec.

Stable link: /guide/errors#guide-aesthetic-incompatible

coord-fixed-free-scales

Code + severity: coord-fixed-free-scales · error

What failed: Spec validation rejected the value at its reported path (schema shape).

Why: Fixed-aspect coordinates cannot represent free positional facet scales truthfully.

Fix: Use facet.scales = "fixed", or remove coord_fixed / coord_sf.

Consequence (blocked): Validation failed; no chart should be rendered from this spec.

Stable link: /guide/errors#coord-fixed-free-scales

missing-required-channel

Code + severity: missing-required-channel · error

What failed: Spec validation rejected the value at its reported path (grammar or data-aware check).

Why: A geom is missing a required aesthetic channel (x, y, label, ...).

Fix: Map the named channel to a data field in the layer's aes or the plot-level aes.

Consequence (blocked): Validation failed; no chart should be rendered from this spec.

Stable link: /guide/errors#missing-required-channel

rule-form-ambiguous

Code + severity: rule-form-ambiguous · error

What failed: Spec validation rejected the value at its reported path (grammar or data-aware check).

Why: A rule layer mixes the annotation form (params.xintercept/yintercept) with mapped aes.x/aes.y.

Fix: Use fixed intercepts OR a data mapping, never both (unset the other with null).

Consequence (blocked): Validation failed; no chart should be rendered from this spec.

Stable link: /guide/errors#rule-form-ambiguous

rule-form-missing

Code + severity: rule-form-missing · error

What failed: Spec validation rejected the value at its reported path (grammar or data-aware check).

Why: A rule layer has neither intercept params nor a mapped aes.x/aes.y — nothing to draw.

Fix: Set params.yintercept/xintercept (annotation) or map aes.x/aes.y (data-driven).

Consequence (blocked): Validation failed; no chart should be rendered from this spec.

Stable link: /guide/errors#rule-form-missing

rule-both-axes

Code + severity: rule-both-axes · error

What failed: Spec validation rejected the value at its reported path (grammar or data-aware check).

Why: A data-driven rule layer maps BOTH aes.x and aes.y (pick one direction).

Fix: Keep one direction (vertical: map x; horizontal: map y) and unset the other with null.

Consequence (blocked): Validation failed; no chart should be rendered from this spec.

Stable link: /guide/errors#rule-both-axes

computed-y-mapped

Code + severity: computed-y-mapped · error

What failed: Spec validation rejected the value at its reported path (grammar or data-aware check).

Why: A layer whose stat computes y (count, bin, density) maps aes.y to a data field.

Fix: Unset y with null — or, for pre-computed bar heights, switch the layer to geom "col".

Consequence (blocked): Validation failed; no chart should be rendered from this spec.

Stable link: /guide/errors#computed-y-mapped

bin-center-and-boundary

Code + severity: bin-center-and-boundary · error

What failed: Spec validation rejected the value at its reported path (grammar or data-aware check).

Why: A bin-stat layer sets BOTH params.center and params.boundary.

Fix: Keep one bin-grid alignment parameter and remove the other.

Consequence (blocked): Validation failed; no chart should be rendered from this spec.

Stable link: /guide/errors#bin-center-and-boundary

facet-form-ambiguous

Code + severity: facet-form-ambiguous · error

What failed: Spec validation rejected the value at its reported path (grammar or data-aware check).

Why: A facet sets BOTH the wrap form and the rows/cols grid form.

Fix: Keep facet.wrap (and drop rows/cols), or keep rows/cols (and drop wrap).

Consequence (blocked): Validation failed; no chart should be rendered from this spec.

Stable link: /guide/errors#facet-form-ambiguous

facet-form-missing

Code + severity: facet-form-missing · error

What failed: Spec validation rejected the value at its reported path (grammar or data-aware check).

Why: A facet sets neither wrap nor rows/cols — nothing to partition by.

Fix: Set facet.wrap (wrap form) or facet.rows/facet.cols (grid form).

Consequence (blocked): Validation failed; no chart should be rendered from this spec.

Stable link: /guide/errors#facet-form-missing

facet-ncol-without-wrap

Code + severity: facet-ncol-without-wrap · error

What failed: Spec validation rejected the value at its reported path (grammar or data-aware check).

Why: facet.ncol only applies to the wrap form.

Fix: Remove ncol, or switch to the wrap form.

Consequence (blocked): Validation failed; no chart should be rendered from this spec.

Stable link: /guide/errors#facet-ncol-without-wrap

unsupported-geom-aesthetic

Code + severity: unsupported-geom-aesthetic · error

What failed: Spec validation rejected the value at its reported path (grammar or data-aware check).

Why: A mapped style aesthetic is not consumed by the selected geom.

Fix: Remove the mapping or move it to one of the compatible geoms listed in the error.

Consequence (blocked): Validation failed; no chart should be rendered from this spec.

Stable link: /guide/errors#unsupported-geom-aesthetic

ribbon-orientation-ambiguous

Code + severity: ribbon-orientation-ambiguous · error

What failed: Spec validation rejected the value at its reported path (grammar or data-aware check).

Why: A ribbon layer maps both x-orientation (x+ymin+ymax) and y-orientation (y+xmin+xmax) contracts without params.orientation.

Fix: Set params.orientation to "x" or "y", or map only one complete interval contract.

Consequence (blocked): Validation failed; no chart should be rendered from this spec.

Stable link: /guide/errors#ribbon-orientation-ambiguous

paint-stops-unordered

Code + severity: paint-stops-unordered · error

What failed: Spec validation rejected the value at its reported path (grammar or data-aware check).

Why: A gradient paint's color stops are not in non-decreasing offset order.

Fix: Sort stops by offset ascending (each offset between 0 and 1 inclusive).

Consequence (blocked): Validation failed; no chart should be rendered from this spec.

Stable link: /guide/errors#paint-stops-unordered

paint-scale-conflict

Code + severity: paint-scale-conflict · error

What failed: Spec validation rejected the value at its reported path (grammar or data-aware check).

Why: Within-mark fillPaint/strokePaint cannot combine with a data-mapped fill/color scale channel.

Fix: Remove the data-mapped fill/color aesthetic, or remove the paint and keep the scale.

Consequence (blocked): Validation failed; no chart should be rendered from this spec.

Stable link: /guide/errors#paint-scale-conflict

unknown-field

Code + severity: unknown-field · error

What failed: Spec validation rejected the value at its reported path (grammar or data-aware check).

Why: A channel maps a field that does not exist in the data.

Fix: Map the channel to one of the available fields (the error lists them, with a did-you-mean).

Consequence (blocked): Validation failed; no chart should be rendered from this spec.

Stable link: /guide/errors#unknown-field

Minimal illustration — copy only the relevant fragment:

{
  "aes": {
    "x": { "field": "weight" },
    "y": { "field": "economy" }
  }
}

all-null-column

Code + severity: all-null-column · error

What failed: Spec validation rejected the value at its reported path (grammar or data-aware check).

Why: A mapped column contains only null values.

Fix: Map the channel to a column with actual values, or fix the data.

Consequence (blocked): Validation failed; no chart should be rendered from this spec.

Stable link: /guide/errors#all-null-column

scale-type-mismatch

Code + severity: scale-type-mismatch · error

What failed: Spec validation rejected the value at its reported path (grammar or data-aware check).

Why: A configured scale type is incompatible with the mapped field's type.

Fix: Change the scale type to match the field (band for categories, time for temporal), or map a compatible field.

Consequence (blocked): Validation failed; no chart should be rendered from this spec.

Stable link: /guide/errors#scale-type-mismatch

channel-type-mismatch

Code + severity: channel-type-mismatch · error

What failed: Spec validation rejected the value at its reported path (grammar or data-aware check).

Why: A mapped field's type is incompatible with the layer's geom/stat (e.g. a nominal x on smooth/bin/density, a continuous x on boxplot).

Fix: Map a field of the type the geom/stat needs, or switch to a geom that fits the field (the message suggests one).

Consequence (blocked): Validation failed; no chart should be rendered from this spec.

Stable link: /guide/errors#channel-type-mismatch

unknown-stat-column

Code + severity: unknown-stat-column · error

What failed: Spec validation rejected the value at its reported path (grammar or data-aware check).

Why: A { stat } channel names a column the layer's stat does not generate.

Fix: Use one of the columns the stat generates (the error lists them), or change the layer's stat.

Consequence (blocked): Validation failed; no chart should be rendered from this spec.

Stable link: /guide/errors#unknown-stat-column

manual-fun-required

Code + severity: manual-fun-required · error

What failed: Spec validation rejected the value at its reported path (grammar or data-aware check).

Why: A layer uses stat manual without params.fun.

Fix: Set params.fun to one of first|last|mean|median|min|max|sum (portable named registry; #814).

Consequence (blocked): Validation failed; no chart should be rendered from this spec.

Stable link: /guide/errors#manual-fun-required

invalid-data-profile

Code + severity: invalid-data-profile · error

What failed: Spec validation rejected the value at its reported path (grammar or data-aware check).

Why: The provided DataProfile is malformed.

Fix: Provide { fields: [{ name, type: "quantitative"|"temporal"|"ordinal"|"nominal" }], rowCount? }.

Consequence (blocked): Validation failed; no chart should be rendered from this spec.

Stable link: /guide/errors#invalid-data-profile

validation-limit

Code + severity: validation-limit · error

What failed: Spec validation rejected the value at its reported path (grammar or data-aware check).

Why: Validation input exceeded a documented limit (rows/bytes/depth/diagnostics).

Fix: Validate with a DataProfile instead of huge inline data, or raise the limit via options.limits.

Consequence (blocked): Validation failed; no chart should be rendered from this spec.

Stable link: /guide/errors#validation-limit

Render-time errors (@ggsvelte/core)

Each entry answers what failed, why, how to recover safely, and whether output was blocked or degraded.

guide-aesthetic-incompatible — pipeline

Code + severity: guide-aesthetic-incompatible · error

What failed: The render pipeline stopped at the path reported by PipelineError.

Why: A guide variant is incompatible with its aesthetic or trained scale family.

Fix: Use axis for x/y, legend for discrete/style scales, colorbar for sequential color, or colorsteps for binned color.

Consequence (blocked): Rendering stopped; ggsvelte does not substitute blank or partial output.

Stable link: /guide/errors#guide-aesthetic-incompatible-pipeline

guide-layout-overflow

Code + severity: guide-layout-overflow · error

What failed: The render pipeline stopped at the path reported by PipelineError.

Why: A guide configured with collision: error cannot fit its authored label.

Fix: Use collision: "ellipsis" for long labels; increase the chart size, reduce categories, or suppress an oversized guide.

Consequence (blocked): Rendering stopped; ggsvelte does not substitute blank or partial output.

Stable link: /guide/errors#guide-layout-overflow

no-data

Code + severity: no-data · error

What failed: The render pipeline stopped at the path reported by PipelineError.

Why: A layer has neither plot-level data nor its own layer.data.

Fix: Set spec.data and/or layer.data ({values}, {columns}, or {name}), or pass named data via RunOptions.data.

Consequence (blocked): Rendering stopped; ggsvelte does not substitute blank or partial output.

Stable link: /guide/errors#no-data

dataset-collision

Code + severity: dataset-collision · error

What failed: The render pipeline stopped at the path reported by PipelineError.

Why: A dataset name is defined in both spec.datasets and RunOptions.data.

Fix: Rename one of them, or pass allowOverride: true to let the runtime data win.

Consequence (blocked): Rendering stopped; ggsvelte does not substitute blank or partial output.

Stable link: /guide/errors#dataset-collision

unknown-dataset

Code + severity: unknown-dataset · error

What failed: The render pipeline stopped at the path reported by PipelineError.

Why: A {"name": ...} data ref names a dataset that is not defined anywhere.

Fix: Define it in spec.datasets or RunOptions.data (the message lists the available names).

Consequence (blocked): Rendering stopped; ggsvelte does not substitute blank or partial output.

Stable link: /guide/errors#unknown-dataset

unknown-field — pipeline

Code + severity: unknown-field · error

What failed: The render pipeline stopped at the path reported by PipelineError.

Why: A channel maps a field that does not exist in the data.

Fix: Map the channel to one of the available fields (the error lists them, with a did-you-mean).

Consequence (blocked): Rendering stopped; ggsvelte does not substitute blank or partial output.

Stable link: /guide/errors#unknown-field-pipeline

all-null-column — pipeline

Code + severity: all-null-column · error

What failed: The render pipeline stopped at the path reported by PipelineError.

Why: A mapped column contains only null values.

Fix: Map the channel to a column with actual values, or fix the data.

Consequence (blocked): Rendering stopped; ggsvelte does not substitute blank or partial output.

Stable link: /guide/errors#all-null-column-pipeline

missing-channel

Code + severity: missing-channel · error

What failed: The render pipeline stopped at the path reported by PipelineError.

Why: A geom is missing a required aesthetic channel at render time.

Fix: Map the named channel in the layer's aes or the plot-level aes.

Consequence (blocked): Rendering stopped; ggsvelte does not substitute blank or partial output.

Stable link: /guide/errors#missing-channel

unknown-stat-column — pipeline

Code + severity: unknown-stat-column · error

What failed: The render pipeline stopped at the path reported by PipelineError.

Why: A { stat } channel names a column the layer's stat does not generate.

Fix: Use one of the columns the stat generates (the error lists them), or change the layer's stat.

Consequence (blocked): Rendering stopped; ggsvelte does not substitute blank or partial output.

Stable link: /guide/errors#unknown-stat-column-pipeline

channel-type-mismatch — pipeline

Code + severity: channel-type-mismatch · error

What failed: The render pipeline stopped at the path reported by PipelineError.

Why: A mapped field's type is incompatible with the layer's geom/stat (e.g. a nominal x on smooth/bin/density, a continuous x on boxplot).

Fix: Map a field of the type the geom/stat needs, or switch to a geom that fits the field (the message suggests one).

Consequence (blocked): Rendering stopped; ggsvelte does not substitute blank or partial output.

Stable link: /guide/errors#channel-type-mismatch-pipeline

computed-y-mapped — pipeline

Code + severity: computed-y-mapped · error

What failed: The render pipeline stopped at the path reported by PipelineError.

Why: A layer whose stat computes y (count, bin, density) maps aes.y to a data field.

Fix: Unset y with null — or, for pre-computed bar heights, switch the layer to geom "col".

Consequence (blocked): Rendering stopped; ggsvelte does not substitute blank or partial output.

Stable link: /guide/errors#computed-y-mapped-pipeline

bin-center-and-boundary — pipeline

Code + severity: bin-center-and-boundary · error

What failed: The render pipeline stopped at the path reported by PipelineError.

Why: A bin-stat layer sets BOTH params.center and params.boundary.

Fix: Keep one bin-grid alignment parameter and remove the other.

Consequence (blocked): Rendering stopped; ggsvelte does not substitute blank or partial output.

Stable link: /guide/errors#bin-center-and-boundary-pipeline

rule-form-ambiguous — pipeline

Code + severity: rule-form-ambiguous · error

What failed: The render pipeline stopped at the path reported by PipelineError.

Why: A rule layer mixes the annotation form (params.xintercept/yintercept) with mapped aes.x/aes.y.

Fix: Use fixed intercepts OR a data mapping, never both (unset the other with null).

Consequence (blocked): Rendering stopped; ggsvelte does not substitute blank or partial output.

Stable link: /guide/errors#rule-form-ambiguous-pipeline

rule-form-missing — pipeline

Code + severity: rule-form-missing · error

What failed: The render pipeline stopped at the path reported by PipelineError.

Why: A rule layer has neither intercept params nor a mapped aes.x/aes.y — nothing to draw.

Fix: Set params.yintercept/xintercept (annotation) or map aes.x/aes.y (data-driven).

Consequence (blocked): Rendering stopped; ggsvelte does not substitute blank or partial output.

Stable link: /guide/errors#rule-form-missing-pipeline

rule-both-axes — pipeline

Code + severity: rule-both-axes · error

What failed: The render pipeline stopped at the path reported by PipelineError.

Why: A data-driven rule layer maps BOTH aes.x and aes.y (pick one direction).

Fix: Keep one direction (vertical: map x; horizontal: map y) and unset the other with null.

Consequence (blocked): Rendering stopped; ggsvelte does not substitute blank or partial output.

Stable link: /guide/errors#rule-both-axes-pipeline

ribbon-orientation-ambiguous — pipeline

Code + severity: ribbon-orientation-ambiguous · error

What failed: The render pipeline stopped at the path reported by PipelineError.

Why: A ribbon layer maps both x-orientation (x+ymin+ymax) and y-orientation (y+xmin+xmax) contracts without params.orientation.

Fix: Set params.orientation to "x" or "y", or map only one complete interval contract.

Consequence (blocked): Rendering stopped; ggsvelte does not substitute blank or partial output.

Stable link: /guide/errors#ribbon-orientation-ambiguous-pipeline

ribbon-inverted-bounds

Code + severity: ribbon-inverted-bounds · error

What failed: The render pipeline stopped at the path reported by PipelineError.

Why: A ribbon layer has one or more rows where the lower bound exceeds the upper bound.

Fix: Swap or correct ymin/ymax (or xmin/xmax) so lower ≤ upper on every finite row.

Consequence (blocked): Rendering stopped; ggsvelte does not substitute blank or partial output.

Stable link: /guide/errors#ribbon-inverted-bounds

facet-form-ambiguous — pipeline

Code + severity: facet-form-ambiguous · error

What failed: The render pipeline stopped at the path reported by PipelineError.

Why: A facet sets BOTH the wrap form and the rows/cols grid form.

Fix: Keep facet.wrap (and drop rows/cols), or keep rows/cols (and drop wrap).

Consequence (blocked): Rendering stopped; ggsvelte does not substitute blank or partial output.

Stable link: /guide/errors#facet-form-ambiguous-pipeline

facet-form-missing — pipeline

Code + severity: facet-form-missing · error

What failed: The render pipeline stopped at the path reported by PipelineError.

Why: A facet sets neither wrap nor rows/cols — nothing to partition by.

Fix: Set facet.wrap (wrap form) or facet.rows/facet.cols (grid form).

Consequence (blocked): Rendering stopped; ggsvelte does not substitute blank or partial output.

Stable link: /guide/errors#facet-form-missing-pipeline

invalid-scale-domain

Code + severity: invalid-scale-domain · error

What failed: The render pipeline stopped at the path reported by PipelineError.

Why: An explicit scale domain is malformed for its scale type.

Fix: Provide a two-element [min, max] for continuous scales (values of the field's type).

Consequence (blocked): Rendering stopped; ggsvelte does not substitute blank or partial output.

Stable link: /guide/errors#invalid-scale-domain

invalid-scale-breaks

Code + severity: invalid-scale-breaks · error

What failed: The render pipeline stopped at the path reported by PipelineError.

Why: One or more explicit scale breaks do not match the scale's parser.

Fix: Use numeric breaks for numeric scales or values matching the temporal parse option.

Consequence (blocked): Rendering stopped; ggsvelte does not substitute blank or partial output.

Stable link: /guide/errors#invalid-scale-breaks

invalid-temporal-labels

Code + severity: invalid-temporal-labels · error

What failed: The render pipeline stopped at the path reported by PipelineError.

Why: A temporal dateLabels string uses an unsupported or incomplete token.

Fix: Use only the documented closed dateLabels token grammar.

Consequence (blocked): Rendering stopped; ggsvelte does not substitute blank or partial output.

Stable link: /guide/errors#invalid-temporal-labels

invalid-temporal-locale

Code + severity: invalid-temporal-locale · error

What failed: The render pipeline stopped at the path reported by PipelineError.

Why: A temporal scale locale is not a valid supported BCP 47 locale.

Fix: Use a canonical BCP 47 locale such as en-US, en-GB, fr-FR, or ja-JP.

Consequence (blocked): Rendering stopped; ggsvelte does not substitute blank or partial output.

Stable link: /guide/errors#invalid-temporal-locale

temporal-parse-failed

Code + severity: temporal-parse-failed · error

What failed: The render pipeline stopped at the path reported by PipelineError.

Why: An explicit temporal parser rejected one or more source values.

Fix: Correct the rejected values, choose the matching parser, or explicitly opt into censoring.

Consequence (blocked): Rendering stopped; ggsvelte does not substitute blank or partial output.

Stable link: /guide/errors#temporal-parse-failed

temporal-break-limit

Code + severity: temporal-break-limit · error

What failed: The render pipeline stopped at the path reported by PipelineError.

Why: An explicit temporal interval would generate more bounded ticks than allowed.

Fix: Choose a coarser calendar interval.

Consequence (blocked): Rendering stopped; ggsvelte does not substitute blank or partial output.

Stable link: /guide/errors#temporal-break-limit

temporal-break-progression

Code + severity: temporal-break-progression · error

What failed: The render pipeline stopped at the path reported by PipelineError.

Why: Calendar interval progression failed to advance monotonically.

Fix: Choose another timezone, disambiguation policy, or interval and report the failing case.

Consequence (blocked): Rendering stopped; ggsvelte does not substitute blank or partial output.

Stable link: /guide/errors#temporal-break-progression

invalid-scale-transform

Code + severity: invalid-scale-transform · error

What failed: The render pipeline stopped at the path reported by PipelineError.

Why: The scale transform registry was asked for an unknown transform key.

Fix: Use a supported transform (identity, log10, sqrt). This indicates malformed runtime input.

Consequence (blocked): Rendering stopped; ggsvelte does not substitute blank or partial output.

Stable link: /guide/errors#invalid-scale-transform

scale-transform-domain

Code + severity: scale-transform-domain · error

What failed: The render pipeline stopped at the path reported by PipelineError.

Why: An explicit scale domain falls outside the transform's valid range (log10 <= 0, sqrt < 0).

Fix: Restrict the domain to the transform's valid range, or use the identity transform.

Consequence (blocked): Rendering stopped; ggsvelte does not substitute blank or partial output.

Stable link: /guide/errors#scale-transform-domain

scale-type-transform-conflict — pipeline

Code + severity: scale-type-transform-conflict · error

What failed: The render pipeline stopped at the path reported by PipelineError.

Why: A scale declares an incompatible type/family with its transform (temporal/discrete/manual/identity with a non-identity transform, or type: "log" with a non-log10 transform).

Fix: Use identity for temporal/discrete/manual/identity scales; for base-10 log use type: "linear" with transform: "log10"; or choose a quantitative family that admits the transform.

Consequence (blocked): Rendering stopped; ggsvelte does not substitute blank or partial output.

Stable link: /guide/errors#scale-type-transform-conflict-pipeline

scale-zero-invalid-for-transform

Code + severity: scale-zero-invalid-for-transform · error

What failed: The render pipeline stopped at the path reported by PipelineError.

Why: zero: true was requested under a transform with no valid image for semantic zero (log10).

Fix: Remove zero: true; log10 positions use the transformed-space origin (semantic 1), never log10(0).

Consequence (blocked): Rendering stopped; ggsvelte does not substitute blank or partial output.

Stable link: /guide/errors#scale-zero-invalid-for-transform

coord-transform-domain

Code + severity: coord-transform-domain · error

What failed: The render pipeline stopped at the path reported by PipelineError.

Why: A post-stat coordinate transform cannot project its trained or explicit viewport domain.

Fix: Choose coordinate limits inside the transform domain, or use the identity coordinate transform.

Consequence (blocked): Rendering stopped; ggsvelte does not substitute blank or partial output.

Stable link: /guide/errors#coord-transform-domain

coord-transform-temporal

Code + severity: coord-transform-temporal · error

What failed: The render pipeline stopped at the path reported by PipelineError.

Why: A non-identity coordinate transform was requested for a temporal axis.

Fix: Keep temporal coordinates on identity; use identity coordinate limits/reverse for a viewport.

Consequence (blocked): Rendering stopped; ggsvelte does not substitute blank or partial output.

Stable link: /guide/errors#coord-transform-temporal

coord-transform-continuous

Code + severity: coord-transform-continuous · error

What failed: The render pipeline stopped at the path reported by PipelineError.

Why: A quantitative coordinate transform or numeric limits were requested for a band axis.

Fix: Use identity coordinates for categories, or configure a continuous quantitative scale.

Consequence (blocked): Rendering stopped; ggsvelte does not substitute blank or partial output.

Stable link: /guide/errors#coord-transform-continuous

coord-fixed-free-scales — pipeline

Code + severity: coord-fixed-free-scales · error

What failed: The render pipeline stopped at the path reported by PipelineError.

Why: Fixed-aspect coordinates cannot represent free positional facet scales truthfully.

Fix: Use facet.scales = "fixed", or remove coord_fixed / coord_sf.

Consequence (blocked): Rendering stopped; ggsvelte does not substitute blank or partial output.

Stable link: /guide/errors#coord-fixed-free-scales-pipeline

coord-fixed-invalid-aspect

Code + severity: coord-fixed-invalid-aspect · error

What failed: The render pipeline stopped at the path reported by PipelineError.

Why: A fixed-aspect target or fitted data rectangle is non-finite or non-positive after chrome is allocated.

Fix: Use a moderate finite ratio and non-degenerate positional domains, or enlarge the plot allocation.

Consequence (blocked): Rendering stopped; ggsvelte does not substitute blank or partial output.

Stable link: /guide/errors#coord-fixed-invalid-aspect

binned-scale-requires-continuous

Code + severity: binned-scale-requires-continuous · error

What failed: The render pipeline stopped at the path reported by PipelineError.

Why: A type: "binned" scale is bound to a discrete or temporal field.

Fix: Map a quantitative field, or use type: "band"/"time" instead of "binned".

Consequence (blocked): Rendering stopped; ggsvelte does not substitute blank or partial output.

Stable link: /guide/errors#binned-scale-requires-continuous

binned-scale-break-limit

Code + severity: binned-scale-break-limit · error

What failed: The render pipeline stopped at the path reported by PipelineError.

Why: A binned scale's automatic or explicit breaks would exceed MAX_BINNED_BREAKS (64).

Fix: Supply fewer explicit breaks, or widen them so automatic binning stays under the limit.

Consequence (blocked): Rendering stopped; ggsvelte does not substitute blank or partial output.

Stable link: /guide/errors#binned-scale-break-limit

palette-exhausted

Code + severity: palette-exhausted · error

What failed: The render pipeline stopped at the path reported by PipelineError.

Why: A discrete color scale with onExhaust: "error" ran out of palette entries (the default "cycle" only warns).

Fix: Provide a larger range, set an explicit domain, or accept cycling by removing onExhaust.

Consequence (blocked): Rendering stopped; ggsvelte does not substitute blank or partial output.

Stable link: /guide/errors#palette-exhausted

color-temporal-parse

Code + severity: color-temporal-parse · error

What failed: The render pipeline stopped at the path reported by PipelineError.

Why: A temporal color/fill scale could not parse the complete mapped column.

Fix: Set the exact parse order, correct the rejected values, or explicitly choose parseFailure: censor.

Consequence (blocked): Rendering stopped; ggsvelte does not substitute blank or partial output.

Stable link: /guide/errors#color-temporal-parse

color-temporal-kind

Code + severity: color-temporal-kind · error

What failed: The render pipeline stopped at the path reported by PipelineError.

Why: A temporal color/fill scale requested date or datetime precision that the data does not have.

Fix: Use the matching date/datetime helper or correct the source precision.

Consequence (blocked): Rendering stopped; ggsvelte does not substitute blank or partial output.

Stable link: /guide/errors#color-temporal-kind

color-manual-domain-range — pipeline

Code + severity: color-manual-domain-range · error

What failed: The render pipeline stopped at the path reported by PipelineError.

Why: A manual color/fill scale has a different number of domain values and range colors.

Fix: Provide exactly one range color for every domain value.

Consequence (blocked): Rendering stopped; ggsvelte does not substitute blank or partial output.

Stable link: /guide/errors#color-manual-domain-range-pipeline

color-binned-breaks

Code + severity: color-binned-breaks · error

What failed: The render pipeline stopped at the path reported by PipelineError.

Why: Binned color/fill boundaries are invalid, unparseable, duplicated, or unordered.

Fix: Provide 2–65 strictly increasing boundaries valid for the parser and transform.

Consequence (blocked): Rendering stopped; ggsvelte does not substitute blank or partial output.

Stable link: /guide/errors#color-binned-breaks

color-binned-empty

Code + severity: color-binned-empty · error

What failed: The render pipeline stopped at the path reported by PipelineError.

Why: A binned color/fill scale has no values inside its parser/transform domain.

Fix: Correct the mapped values, parser, or transform, or provide a valid explicit domain.

Consequence (blocked): Rendering stopped; ggsvelte does not substitute blank or partial output.

Stable link: /guide/errors#color-binned-empty

color-binned-domain

Code + severity: color-binned-domain · error

What failed: The render pipeline stopped at the path reported by PipelineError.

Why: A binned color/fill domain is degenerate or invalid for its transform.

Fix: Provide two distinct domain endpoints valid for identity, log10, or sqrt.

Consequence (blocked): Rendering stopped; ggsvelte does not substitute blank or partial output.

Stable link: /guide/errors#color-binned-domain

color-domain-invalid

Code + severity: color-domain-invalid · error

What failed: The render pipeline stopped at the path reported by PipelineError.

Why: A sequential color/fill domain does not contain exactly two parseable values.

Fix: Provide a two-value semantic domain matching the mapped field and parser.

Consequence (blocked): Rendering stopped; ggsvelte does not substitute blank or partial output.

Stable link: /guide/errors#color-domain-invalid

color-transform-empty

Code + severity: color-transform-empty · error

What failed: The render pipeline stopped at the path reported by PipelineError.

Why: Every mapped color/fill value is invalid for the requested transform.

Fix: Correct the mapped data or choose a transform whose domain contains the values.

Consequence (blocked): Rendering stopped; ggsvelte does not substitute blank or partial output.

Stable link: /guide/errors#color-transform-empty

color-domain-transform

Code + severity: color-domain-transform · error

What failed: The render pipeline stopped at the path reported by PipelineError.

Why: A sequential color/fill domain is invalid for its requested transform.

Fix: Use positive endpoints for log10, non-negative endpoints for sqrt, or identity.

Consequence (blocked): Rendering stopped; ggsvelte does not substitute blank or partial output.

Stable link: /guide/errors#color-domain-transform

unsupported-aesthetic-scale

Code + severity: unsupported-aesthetic-scale · error

What failed: The render pipeline stopped at the path reported by PipelineError.

Why: A finite shape/linetype aesthetic was configured as a continuous scale.

Fix: Use a binned scale for quantitative values or an ordinal scale for categories.

Consequence (blocked): Rendering stopped; ggsvelte does not substitute blank or partial output.

Stable link: /guide/errors#unsupported-aesthetic-scale

unsupported-geom-aesthetic — pipeline

Code + severity: unsupported-geom-aesthetic · error

What failed: The render pipeline stopped at the path reported by PipelineError.

Why: A mapped style aesthetic is not consumed by the selected geom.

Fix: Remove the mapping or move it to one of the compatible geoms listed in the error.

Consequence (blocked): Rendering stopped; ggsvelte does not substitute blank or partial output.

Stable link: /guide/errors#unsupported-geom-aesthetic-pipeline

unsupported-annotation-style

Code + severity: unsupported-annotation-style · error

What failed: The render pipeline stopped at the path reported by PipelineError.

Why: A fixed-intercept annotation rule maps a style to a field or after-stat column, but it has no data rows to map.

Fix: Use a constant style value (optionally { value, scale: true }) on the annotation rule.

Consequence (blocked): Rendering stopped; ggsvelte does not substitute blank or partial output.

Stable link: /guide/errors#unsupported-annotation-style

tile-nonpositive-size

Code + severity: tile-nonpositive-size · error

What failed: The render pipeline stopped at the path reported by PipelineError.

Why: A tile layer has a non-positive or non-finite width/height.

Fix: Map a positive width/height or set params.width / params.height to a positive number.

Consequence (blocked): Rendering stopped; ggsvelte does not substitute blank or partial output.

Stable link: /guide/errors#tile-nonpositive-size

raster-duplicate-cells

Code + severity: raster-duplicate-cells · error

What failed: The render pipeline stopped at the path reported by PipelineError.

Why: A raster layer has duplicate (x, y) coordinates.

Fix: Aggregate to one value per cell, or use geom "tile" for overlapping cells.

Consequence (blocked): Rendering stopped; ggsvelte does not substitute blank or partial output.

Stable link: /guide/errors#raster-duplicate-cells

unsupported-param

Code + severity: unsupported-param · error

What failed: The render pipeline stopped at the path reported by PipelineError.

Why: A layer param value is not supported by this runtime.

Fix: Use a documented supported value for the param (see the error message).

Consequence (blocked): Rendering stopped; ggsvelte does not substitute blank or partial output.

Stable link: /guide/errors#unsupported-param

invalid-aesthetic-constant

Code + severity: invalid-aesthetic-constant · error

What failed: The render pipeline stopped at the path reported by PipelineError.

Why: A literal style constant is outside the aesthetic's supported output domain.

Fix: Use a positive size/linewidth, alpha in [0,1], or a documented shape/linetype name.

Consequence (blocked): Rendering stopped; ggsvelte does not substitute blank or partial output.

Stable link: /guide/errors#invalid-aesthetic-constant

style-temporal-parse

Code + severity: style-temporal-parse · error

What failed: The render pipeline stopped at the path reported by PipelineError.

Why: A temporal numeric style scale could not parse the complete mapped column.

Fix: Set the exact parser, correct the rejected values, or explicitly choose censoring.

Consequence (blocked): Rendering stopped; ggsvelte does not substitute blank or partial output.

Stable link: /guide/errors#style-temporal-parse

style-temporal-kind

Code + severity: style-temporal-kind · error

What failed: The render pipeline stopped at the path reported by PipelineError.

Why: A temporal numeric style scale requested the wrong date/datetime precision.

Fix: Use the matching date/datetime helper or correct the source precision.

Consequence (blocked): Rendering stopped; ggsvelte does not substitute blank or partial output.

Stable link: /guide/errors#style-temporal-kind

style-manual-domain-range

Code + severity: style-manual-domain-range · error

What failed: The render pipeline stopped at the path reported by PipelineError.

Why: A manual style scale has different domain and range lengths.

Fix: Provide exactly one output style for every domain value.

Consequence (blocked): Rendering stopped; ggsvelte does not substitute blank or partial output.

Stable link: /guide/errors#style-manual-domain-range

style-palette-exhausted

Code + severity: style-palette-exhausted · error

What failed: The render pipeline stopped at the path reported by PipelineError.

Why: A finite style scale needs more distinguishable outputs than its range provides.

Fix: Provide a larger range, reduce categories/bins, or deliberately opt into cycling.

Consequence (blocked): Rendering stopped; ggsvelte does not substitute blank or partial output.

Stable link: /guide/errors#style-palette-exhausted

style-domain-empty

Code + severity: style-domain-empty · error

What failed: The render pipeline stopped at the path reported by PipelineError.

Why: No finite values can train the requested numeric or binned style scale.

Fix: Correct the mapped values or provide a valid explicit domain.

Consequence (blocked): Rendering stopped; ggsvelte does not substitute blank or partial output.

Stable link: /guide/errors#style-domain-empty

style-domain-invalid

Code + severity: style-domain-invalid · error

What failed: The render pipeline stopped at the path reported by PipelineError.

Why: An explicit style domain is malformed or contradicts its binned boundaries.

Fix: Provide two finite semantic endpoints matching the first and last boundaries.

Consequence (blocked): Rendering stopped; ggsvelte does not substitute blank or partial output.

Stable link: /guide/errors#style-domain-invalid

style-range-invalid

Code + severity: style-range-invalid · error

What failed: The render pipeline stopped at the path reported by PipelineError.

Why: A numeric sequential/binned style range has fewer than two endpoints.

Fix: Provide at least two valid output values in the aesthetic's supported bounds.

Consequence (blocked): Rendering stopped; ggsvelte does not substitute blank or partial output.

Stable link: /guide/errors#style-range-invalid

style-binned-breaks

Code + severity: style-binned-breaks · error

What failed: The render pipeline stopped at the path reported by PipelineError.

Why: Binned style boundaries are missing, non-finite, duplicated, or unordered.

Fix: Provide 2–65 strictly increasing numeric boundaries.

Consequence (blocked): Rendering stopped; ggsvelte does not substitute blank or partial output.

Stable link: /guide/errors#style-binned-breaks

stat-channel-unsupported

Code + severity: stat-channel-unsupported · error

What failed: The render pipeline stopped at the path reported by PipelineError.

Why: A { stat } style mapping names an output the selected stat does not publish.

Fix: Use a generated output listed for that stat or map the original field instead.

Consequence (blocked): Rendering stopped; ggsvelte does not substitute blank or partial output.

Stable link: /guide/errors#stat-channel-unsupported

manual-fun-required — pipeline

Code + severity: manual-fun-required · error

What failed: The render pipeline stopped at the path reported by PipelineError.

Why: A layer uses stat manual without params.fun.

Fix: Set params.fun to one of first|last|mean|median|min|max|sum (portable named registry; #814).

Consequence (blocked): Rendering stopped; ggsvelte does not substitute blank or partial output.

Stable link: /guide/errors#manual-fun-required-pipeline

manual-fun-unknown

Code + severity: manual-fun-unknown · error

What failed: The render pipeline stopped at the path reported by PipelineError.

Why: A layer uses stat manual with an unregistered params.fun (defense for unvalidated specs).

Fix: Use a registered name: first, last, mean, median, min, max, sum.

Consequence (blocked): Rendering stopped; ggsvelte does not substitute blank or partial output.

Stable link: /guide/errors#manual-fun-unknown

unknown-theme

Code + severity: unknown-theme · error

What failed: The render pipeline stopped at the path reported by PipelineError.

Why: spec.theme names a theme that is not registered.

Fix: Use a registered name (default, light, dark, minimal) or a theme object.

Consequence (blocked): Rendering stopped; ggsvelte does not substitute blank or partial output.

Stable link: /guide/errors#unknown-theme

renderer-failure

Code + severity: renderer-failure · error

What failed: The render pipeline stopped at the path reported by PipelineError.

Why: The SVG renderer threw while drawing a scene (never blank output — failure policy).

Fix: This is a ggsvelte bug; the message carries the underlying error. Please report it.

Consequence (blocked): Rendering stopped; ggsvelte does not substitute blank or partial output.

Stable link: /guide/errors#renderer-failure

max-marks-exceeded

Code + severity: max-marks-exceeded · error

What failed: The render pipeline stopped at the path reported by PipelineError.

Why: renderToSVGString refused to render more marks than its maxMarks safety limit.

Fix: Raise options.maxMarks deliberately, reduce the data, or render interactively (canvas).

Consequence (blocked): Rendering stopped; ggsvelte does not substitute blank or partial output.

Stable link: /guide/errors#max-marks-exceeded

sf-geometry-missing

Code + severity: sf-geometry-missing · error

What failed: The render pipeline stopped at the path reported by PipelineError.

Why: geom_sf data is missing the geometry column.

Fix: Provide a column of GeoJSON Geometry JSON strings (default field "geometry", or params.geometry).

Consequence (blocked): Rendering stopped; ggsvelte does not substitute blank or partial output.

Stable link: /guide/errors#sf-geometry-missing

sf-geometry-invalid

Code + severity: sf-geometry-invalid · error

What failed: The render pipeline stopped at the path reported by PipelineError.

Why: A geom_sf geometry cell could not be parsed as drawable GeoJSON Geometry.

Fix: Use valid GeoJSON Geometry JSON strings with finite coordinates.

Consequence (blocked): Rendering stopped; ggsvelte does not substitute blank or partial output.

Stable link: /guide/errors#sf-geometry-invalid

sf-geometry-unsupported

Code + severity: sf-geometry-unsupported · error

What failed: The render pipeline stopped at the path reported by PipelineError.

Why: geom_sf received a GeoJSON type outside the v1 point/line/polygon families.

Fix: Use Point/MultiPoint, LineString/MultiLineString, Polygon/MultiPolygon, or GeometryCollection of those families (no CRS).

Consequence (blocked): Rendering stopped; ggsvelte does not substitute blank or partial output.

Stable link: /guide/errors#sf-geometry-unsupported

sf-geometry-mixed

Code + severity: sf-geometry-mixed · error

What failed: The render pipeline stopped at the path reported by PipelineError.

Why: One geom_sf layer mixes geometry families (point vs line vs polygon).

Fix: Split mixed types into separate geom_sf layers (v1 is single-family per layer).

Consequence (blocked): Rendering stopped; ggsvelte does not substitute blank or partial output.

Stable link: /guide/errors#sf-geometry-mixed

map-data-required

Code + severity: map-data-required · error

What failed: The render pipeline stopped at the path reported by PipelineError.

Why: geom_map was used without params.map.

Fix: Pass params.map as { values }, { columns }, or { name } against spec.datasets.

Consequence (blocked): Rendering stopped; ggsvelte does not substitute blank or partial output.

Stable link: /guide/errors#map-data-required

map-coords-missing

Code + severity: map-coords-missing · error

What failed: The render pipeline stopped at the path reported by PipelineError.

Why: Map data is missing long/lat or x/y coordinate columns.

Fix: Provide "long"+"lat" or "x"+"y" columns in the fortified map table.

Consequence (blocked): Rendering stopped; ggsvelte does not substitute blank or partial output.

Stable link: /guide/errors#map-coords-missing

map-id-column-missing

Code + severity: map-id-column-missing · error

What failed: The render pipeline stopped at the path reported by PipelineError.

Why: Map data is missing a region join column.

Fix: Set params.mapId or include a "region" / "id" column in the map table.

Consequence (blocked): Rendering stopped; ggsvelte does not substitute blank or partial output.

Stable link: /guide/errors#map-id-column-missing

Render warnings

Each entry answers what failed, why, how to recover safely, and whether output was blocked or degraded.

facet-levels-missing

Code + severity: facet-levels-missing · warning

What failed: A render step could not use every requested row, value, or default exactly as supplied.

Why: An explicit facet levels list includes values absent from the data; empty panels are kept.

Fix: Inspect the warning message for its path and count, then correct the named data, scale, or option.

Consequence (degraded): The chart rendered, but the warning identifies dropped, cycled, or fallback output.

Stable link: /guide/errors#facet-levels-missing

facet-levels-unknown

Code + severity: facet-levels-unknown · warning

What failed: A render step could not use every requested row, value, or default exactly as supplied.

Why: Data values for a facet field were omitted from the closed levels list and are excluded from every panel.

Fix: Inspect the warning message for its path and count, then correct the named data, scale, or option.

Consequence (degraded): The chart rendered, but the warning identifies dropped, cycled, or fallback output.

Stable link: /guide/errors#facet-levels-unknown

empty-data

Code + severity: empty-data · warning

What failed: A render step could not use every requested row, value, or default exactly as supplied.

Why: The data has no rows; the frame and axes render as a placeholder.

Fix: Inspect the warning message for its path and count, then correct the named data, scale, or option.

Consequence (degraded): The chart rendered, but the warning identifies dropped, cycled, or fallback output.

Stable link: /guide/errors#empty-data

empty-layer

Code + severity: empty-layer · warning

What failed: A render step could not use every requested row, value, or default exactly as supplied.

Why: A layer produced no drawable marks after stats/positions; it was skipped.

Fix: Inspect the warning message for its path and count, then correct the named data, scale, or option.

Consequence (degraded): The chart rendered, but the warning identifies dropped, cycled, or fallback output.

Stable link: /guide/errors#empty-layer

empty-domain

Code + severity: empty-domain · warning

What failed: A render step could not use every requested row, value, or default exactly as supplied.

Why: A positional scale found no finite values; a placeholder domain is used.

Fix: Inspect the warning message for its path and count, then correct the named data, scale, or option.

Consequence (degraded): The chart rendered, but the warning identifies dropped, cycled, or fallback output.

Stable link: /guide/errors#empty-domain

removed-missing

Code + severity: removed-missing · warning

What failed: A render step could not use every requested row, value, or default exactly as supplied.

Why: Rows with missing/non-finite values in required channels were dropped (count in message).

Fix: Inspect the warning message for its path and count, then correct the named data, scale, or option.

Consequence (degraded): The chart rendered, but the warning identifies dropped, cycled, or fallback output.

Stable link: /guide/errors#removed-missing

raster-irregular-spacing

Code + severity: raster-irregular-spacing · warning

What failed: A render step could not use every requested row, value, or default exactly as supplied.

Why: Raster cell centers are not on a regular grid; the minimum spacing is used (prefer geom tile).

Fix: Inspect the warning message for its path and count, then correct the named data, scale, or option.

Consequence (degraded): The chart rendered, but the warning identifies dropped, cycled, or fallback output.

Stable link: /guide/errors#raster-irregular-spacing

scale-transform-domain — warning

Code + severity: scale-transform-domain · warning

What failed: A render step could not use every requested row, value, or default exactly as supplied.

Why: A pre-stat transform dropped values outside its domain (log10 <= 0, sqrt < 0); count in message.

Fix: Inspect the warning message for its path and count, then correct the named data, scale, or option.

Consequence (degraded): The chart rendered, but the warning identifies dropped, cycled, or fallback output.

Stable link: /guide/errors#scale-transform-domain-warning

scale-oob-censored

Code + severity: scale-oob-censored · warning

What failed: A render step could not use every requested row, value, or default exactly as supplied.

Why: Values outside explicit source limits were censored to missing before stats.

Fix: Inspect the warning message for its path and count, then correct the named data, scale, or option.

Consequence (degraded): The chart rendered, but the warning identifies dropped, cycled, or fallback output.

Stable link: /guide/errors#scale-oob-censored

scale-oob-squished

Code + severity: scale-oob-squished · warning

What failed: A render step could not use every requested row, value, or default exactly as supplied.

Why: Values outside explicit source limits were squished to the nearest limit before stats.

Fix: Inspect the warning message for its path and count, then correct the named data, scale, or option.

Consequence (degraded): The chart rendered, but the warning identifies dropped, cycled, or fallback output.

Stable link: /guide/errors#scale-oob-squished

scale-break-outside-domain

Code + severity: scale-break-outside-domain · warning

What failed: A render step could not use every requested row, value, or default exactly as supplied.

Why: One or more explicit continuous breaks were outside the trained display domain and omitted.

Fix: Inspect the warning message for its path and count, then correct the named data, scale, or option.

Consequence (degraded): The chart rendered, but the warning identifies dropped, cycled, or fallback output.

Stable link: /guide/errors#scale-break-outside-domain

sequential-discrete-field

Code + severity: sequential-discrete-field · warning

What failed: A render step could not use every requested row, value, or default exactly as supplied.

Why: A sequential color scale is fed a discrete field; unparseable values render unknown.

Fix: Inspect the warning message for its path and count, then correct the named data, scale, or option.

Consequence (degraded): The chart rendered, but the warning identifies dropped, cycled, or fallback output.

Stable link: /guide/errors#sequential-discrete-field

color-temporal-censored

Code + severity: color-temporal-censored · warning

What failed: A render step could not use every requested row, value, or default exactly as supplied.

Why: A temporal color/fill parser censored invalid source values by explicit author request.

Fix: Inspect the warning message for its path and count, then correct the named data, scale, or option.

Consequence (degraded): The chart rendered, but the warning identifies dropped, cycled, or fallback output.

Stable link: /guide/errors#color-temporal-censored

color-transform-invalid

Code + severity: color-transform-invalid · warning

What failed: A render step could not use every requested row, value, or default exactly as supplied.

Why: Some color/fill values are outside the requested transform domain and render unknown.

Fix: Inspect the warning message for its path and count, then correct the named data, scale, or option.

Consequence (degraded): The chart rendered, but the warning identifies dropped, cycled, or fallback output.

Stable link: /guide/errors#color-transform-invalid

color-na-values

Code + severity: color-na-values · warning

What failed: A render step could not use every requested row, value, or default exactly as supplied.

Why: Missing color/fill values render with the configured NA color (count in message).

Fix: Inspect the warning message for its path and count, then correct the named data, scale, or option.

Consequence (degraded): The chart rendered, but the warning identifies dropped, cycled, or fallback output.

Stable link: /guide/errors#color-na-values

color-unknown-values

Code + severity: color-unknown-values · warning

What failed: A render step could not use every requested row, value, or default exactly as supplied.

Why: Invalid, unmapped, transformed, or censored color/fill values render with the configured unknown color (count in message).

Fix: Inspect the warning message for its path and count, then correct the named data, scale, or option.

Consequence (degraded): The chart rendered, but the warning identifies dropped, cycled, or fallback output.

Stable link: /guide/errors#color-unknown-values

style-temporal-censored

Code + severity: style-temporal-censored · warning

What failed: A render step could not use every requested row, value, or default exactly as supplied.

Why: A temporal numeric style parser censored invalid source values by explicit request.

Fix: Inspect the warning message for its path and count, then correct the named data, scale, or option.

Consequence (degraded): The chart rendered, but the warning identifies dropped, cycled, or fallback output.

Stable link: /guide/errors#style-temporal-censored

style-na-values

Code + severity: style-na-values · warning

What failed: A render step could not use every requested row, value, or default exactly as supplied.

Why: Missing mapped style values use the configured NA output.

Fix: Inspect the warning message for its path and count, then correct the named data, scale, or option.

Consequence (degraded): The chart rendered, but the warning identifies dropped, cycled, or fallback output.

Stable link: /guide/errors#style-na-values

style-unknown-values

Code + severity: style-unknown-values · warning

What failed: A render step could not use every requested row, value, or default exactly as supplied.

Why: Invalid or out-of-domain mapped style values use the configured unknown output.

Fix: Inspect the warning message for its path and count, then correct the named data, scale, or option.

Consequence (degraded): The chart rendered, but the warning identifies dropped, cycled, or fallback output.

Stable link: /guide/errors#style-unknown-values

style-palette-exhausted — warning

Code + severity: style-palette-exhausted · warning

What failed: A render step could not use every requested row, value, or default exactly as supplied.

Why: A finite style range cycled after explicit author opt-in.

Fix: Inspect the warning message for its path and count, then correct the named data, scale, or option.

Consequence (degraded): The chart rendered, but the warning identifies dropped, cycled, or fallback output.

Stable link: /guide/errors#style-palette-exhausted-warning

style-fingerprint-mismatch

Code + severity: style-fingerprint-mismatch · warning

What failed: A render step could not use every requested row, value, or default exactly as supplied.

Why: Restored style state used a different output range; assignments start fresh.

Fix: Inspect the warning message for its path and count, then correct the named data, scale, or option.

Consequence (degraded): The chart rendered, but the warning identifies dropped, cycled, or fallback output.

Stable link: /guide/errors#style-fingerprint-mismatch

style-version-mismatch

Code + severity: style-version-mismatch · warning

What failed: A render step could not use every requested row, value, or default exactly as supplied.

Why: Restored style state has an unknown schema version; assignments start fresh.

Fix: Inspect the warning message for its path and count, then correct the named data, scale, or option.

Consequence (degraded): The chart rendered, but the warning identifies dropped, cycled, or fallback output.

Stable link: /guide/errors#style-version-mismatch

style-out-of-domain

Code + severity: style-out-of-domain · warning

What failed: A render step could not use every requested row, value, or default exactly as supplied.

Why: Values outside an explicit style domain use the unknown output.

Fix: Inspect the warning message for its path and count, then correct the named data, scale, or option.

Consequence (degraded): The chart rendered, but the warning identifies dropped, cycled, or fallback output.

Stable link: /guide/errors#style-out-of-domain

invalid-label-format

Code + severity: invalid-label-format · warning

What failed: A render step could not use every requested row, value, or default exactly as supplied.

Why: A labels format string was not recognized; the default format is used.

Fix: Inspect the warning message for its path and count, then correct the named data, scale, or option.

Consequence (degraded): The chart rendered, but the warning identifies dropped, cycled, or fallback output.

Stable link: /guide/errors#invalid-label-format

unknown-edition

Code + severity: unknown-edition · warning

What failed: A render step could not use every requested row, value, or default exactly as supplied.

Why: The spec targets a defaults edition this build does not know; the latest known edition's defaults are used.

Fix: Inspect the warning message for its path and count, then correct the named data, scale, or option.

Consequence (degraded): The chart rendered, but the warning identifies dropped, cycled, or fallback output.

Stable link: /guide/errors#unknown-edition

color-on-fill-geom

Code + severity: color-on-fill-geom · warning

What failed: A render step could not use every requested row, value, or default exactly as supplied.

Why: The color channel is mapped on a fill-styled geom (bar/col/area); fill is what varies.

Fix: Inspect the warning message for its path and count, then correct the named data, scale, or option.

Consequence (degraded): The chart rendered, but the warning identifies dropped, cycled, or fallback output.

Stable link: /guide/errors#color-on-fill-geom

weight-unsupported

Code + severity: weight-unsupported · warning

What failed: A render step could not use every requested row, value, or default exactly as supplied.

Why: aes.weight is mapped on a stat that does not consume weights.

Fix: Inspect the warning message for its path and count, then correct the named data, scale, or option.

Consequence (degraded): The chart rendered, but the warning identifies dropped, cycled, or fallback output.

Stable link: /guide/errors#weight-unsupported

density-group-dropped

Code + severity: density-group-dropped · warning

What failed: A render step could not use every requested row, value, or default exactly as supplied.

Why: A density group had too few finite values and was dropped.

Fix: Inspect the warning message for its path and count, then correct the named data, scale, or option.

Consequence (degraded): The chart rendered, but the warning identifies dropped, cycled, or fallback output.

Stable link: /guide/errors#density-group-dropped

contour-group-dropped

Code + severity: contour-group-dropped · warning

What failed: A render step could not use every requested row, value, or default exactly as supplied.

Why: A contour group lacked a usable 2D grid or levels and was dropped.

Fix: Inspect the warning message for its path and count, then correct the named data, scale, or option.

Consequence (degraded): The chart rendered, but the warning identifies dropped, cycled, or fallback output.

Stable link: /guide/errors#contour-group-dropped

density-2d-group-dropped

Code + severity: density-2d-group-dropped · warning

What failed: A render step could not use every requested row, value, or default exactly as supplied.

Why: A density_2d group had too few points or produced no contours and was dropped.

Fix: Inspect the warning message for its path and count, then correct the named data, scale, or option.

Consequence (degraded): The chart rendered, but the warning identifies dropped, cycled, or fallback output.

Stable link: /guide/errors#density-2d-group-dropped

density-2d-filled-open-dropped

Code + severity: density-2d-filled-open-dropped · warning

What failed: A render step could not use every requested row, value, or default exactly as supplied.

Why: density_2d_filled dropped open isoline rings; v1 fills closed rings only.

Fix: Inspect the warning message for its path and count, then correct the named data, scale, or option.

Consequence (degraded): The chart rendered, but the warning identifies dropped, cycled, or fallback output.

Stable link: /guide/errors#density-2d-filled-open-dropped

sf-coordinates-dropped

Code + severity: sf-coordinates-dropped · warning

What failed: A render step could not use every requested row, value, or default exactly as supplied.

Why: stat_sf_coordinates dropped features with no finite representative point.

Fix: Inspect the warning message for its path and count, then correct the named data, scale, or option.

Consequence (degraded): The chart rendered, but the warning identifies dropped, cycled, or fallback output.

Stable link: /guide/errors#sf-coordinates-dropped

map-region-missing

Code + severity: map-region-missing · warning

What failed: A render step could not use every requested row, value, or default exactly as supplied.

Why: One or more value rows had no matching map region and were dropped.

Fix: Inspect the warning message for its path and count, then correct the named data, scale, or option.

Consequence (degraded): The chart rendered, but the warning identifies dropped, cycled, or fallback output.

Stable link: /guide/errors#map-region-missing

smooth-group-dropped

Code + severity: smooth-group-dropped · warning

What failed: A render step could not use every requested row, value, or default exactly as supplied.

Why: A smooth group had too few points for the fit and was dropped.

Fix: Inspect the warning message for its path and count, then correct the named data, scale, or option.

Consequence (degraded): The chart rendered, but the warning identifies dropped, cycled, or fallback output.

Stable link: /guide/errors#smooth-group-dropped

quantile-empty

Code + severity: quantile-empty · warning

What failed: A render step could not use every requested row, value, or default exactly as supplied.

Why: No valid quantiles in (0,1) after filtering; nothing drawn.

Fix: Inspect the warning message for its path and count, then correct the named data, scale, or option.

Consequence (degraded): The chart rendered, but the warning identifies dropped, cycled, or fallback output.

Stable link: /guide/errors#quantile-empty

quantile-group-dropped

Code + severity: quantile-group-dropped · warning

What failed: A render step could not use every requested row, value, or default exactly as supplied.

Why: A quantile group was too small or had constant x and was dropped.

Fix: Inspect the warning message for its path and count, then correct the named data, scale, or option.

Consequence (degraded): The chart rendered, but the warning identifies dropped, cycled, or fallback output.

Stable link: /guide/errors#quantile-group-dropped

manual-group-dropped

Code + severity: manual-group-dropped · warning

What failed: A render step could not use every requested row, value, or default exactly as supplied.

Why: A manual-stat group had no finite x or y under an aggregate fun and was dropped.

Fix: Inspect the warning message for its path and count, then correct the named data, scale, or option.

Consequence (degraded): The chart rendered, but the warning identifies dropped, cycled, or fallback output.

Stable link: /guide/errors#manual-group-dropped

ellipse-group-dropped

Code + severity: ellipse-group-dropped · warning

What failed: A render step could not use every requested row, value, or default exactly as supplied.

Why: An ellipse group had fewer than two finite (x,y) points or zero variance and was dropped.

Fix: Inspect the warning message for its path and count, then correct the named data, scale, or option.

Consequence (degraded): The chart rendered, but the warning identifies dropped, cycled, or fallback output.

Stable link: /guide/errors#ellipse-group-dropped

stat-channel-unsupported — warning

Code + severity: stat-channel-unsupported · warning

What failed: A render step could not use every requested row, value, or default exactly as supplied.

Why: A color/fill after-stat mapping names an output the selected stat does not publish; the mapping is ignored (style channels throw the same code as an error).

Fix: Inspect the warning message for its path and count, then correct the named data, scale, or option.

Consequence (degraded): The chart rendered, but the warning identifies dropped, cycled, or fallback output.

Stable link: /guide/errors#stat-channel-unsupported-warning

palette-exhausted — warning

Code + severity: palette-exhausted · warning

What failed: A render step could not use every requested row, value, or default exactly as supplied.

Why: A discrete color scale ran out of palette entries and cycled (the default onExhaust).

Fix: Inspect the warning message for its path and count, then correct the named data, scale, or option.

Consequence (degraded): The chart rendered, but the warning identifies dropped, cycled, or fallback output.

Stable link: /guide/errors#palette-exhausted-warning

fingerprint-mismatch

Code + severity: fingerprint-mismatch · warning

What failed: A render step could not use every requested row, value, or default exactly as supplied.

Why: Restored scale state was trained on a different palette; assignments start fresh.

Fix: Inspect the warning message for its path and count, then correct the named data, scale, or option.

Consequence (degraded): The chart rendered, but the warning identifies dropped, cycled, or fallback output.

Stable link: /guide/errors#fingerprint-mismatch

version-mismatch

Code + severity: version-mismatch · warning

What failed: A render step could not use every requested row, value, or default exactly as supplied.

Why: Restored scale state has an unknown schema version; assignments start fresh.

Fix: Inspect the warning message for its path and count, then correct the named data, scale, or option.

Consequence (degraded): The chart rendered, but the warning identifies dropped, cycled, or fallback output.

Stable link: /guide/errors#version-mismatch

out-of-domain

Code + severity: out-of-domain · warning

What failed: A render step could not use every requested row, value, or default exactly as supplied.

Why: Values outside an explicit scale domain render the unknown color (deduplicated).

Fix: Inspect the warning message for its path and count, then correct the named data, scale, or option.

Consequence (degraded): The chart rendered, but the warning identifies dropped, cycled, or fallback output.

Stable link: /guide/errors#out-of-domain

temporal-values-censored

Code + severity: temporal-values-censored · warning

What failed: A render step could not use every requested row, value, or default exactly as supplied.

Why: An explicit temporal parser censored invalid source values by author request.

Fix: Inspect the warning message for its path and count, then correct the named data, scale, or option.

Consequence (degraded): The chart rendered, but the warning identifies dropped, cycled, or fallback output.

Stable link: /guide/errors#temporal-values-censored

guide-auto-bottom

Code + severity: guide-auto-bottom · warning

What failed: A render step could not use every requested row, value, or default exactly as supplied.

Why: An auto-positioned guide moved below the panel to preserve readable width.

Fix: Inspect the warning message for its path and count, then correct the named data, scale, or option.

Consequence (degraded): The chart rendered, but the warning identifies dropped, cycled, or fallback output.

Stable link: /guide/errors#guide-auto-bottom

unused-scale-option

Code + severity: unused-scale-option · warning

What failed: A render step could not use every requested row, value, or default exactly as supplied.

Why: A lower-precedence scale option was ignored in favor of an explicit winner.

Fix: Inspect the warning message for its path and count, then correct the named data, scale, or option.

Consequence (degraded): The chart rendered, but the warning identifies dropped, cycled, or fallback output.

Stable link: /guide/errors#unused-scale-option

temporal-label-overlap

Code + severity: temporal-label-overlap · warning

What failed: A render step could not use every requested row, value, or default exactly as supplied.

Why: Authored or exhausted automatic temporal labels overlap at the available extent.

Fix: Inspect the warning message for its path and count, then correct the named data, scale, or option.

Consequence (degraded): The chart rendered, but the warning identifies dropped, cycled, or fallback output.

Stable link: /guide/errors#temporal-label-overlap

temporal-label-margin-overflow

Code + severity: temporal-label-margin-overflow · warning

What failed: A render step could not use every requested row, value, or default exactly as supplied.

Why: A complete temporal label exceeds the bounded axis margin.

Fix: Inspect the warning message for its path and count, then correct the named data, scale, or option.

Consequence (degraded): The chart rendered, but the warning identifies dropped, cycled, or fallback output.

Stable link: /guide/errors#temporal-label-margin-overflow

temporal-break-outside-domain

Code + severity: temporal-break-outside-domain · warning

What failed: A render step could not use every requested row, value, or default exactly as supplied.

Why: One or more explicit temporal breaks were outside the trained domain and omitted.

Fix: Inspect the warning message for its path and count, then correct the named data, scale, or option.

Consequence (degraded): The chart rendered, but the warning identifies dropped, cycled, or fallback output.

Stable link: /guide/errors#temporal-break-outside-domain

band-label-overlap

Code + severity: band-label-overlap · warning

What failed: A render step could not use every requested row, value, or default exactly as supplied.

Why: Categorical (band) axis labels overlap even after wrapping and rotation.

Fix: Inspect the warning message for its path and count, then correct the named data, scale, or option.

Consequence (degraded): The chart rendered, but the warning identifies dropped, cycled, or fallback output.

Stable link: /guide/errors#band-label-overlap

band-label-margin-overflow

Code + severity: band-label-margin-overflow · warning

What failed: A render step could not use every requested row, value, or default exactly as supplied.

Why: A band label exceeds a bounded axis margin — single-line end truncation, forced-wrap height/side overflow, or a rotated label past the bottom/side cap.

Fix: Inspect the warning message for its path and count, then correct the named data, scale, or option.

Consequence (degraded): The chart rendered, but the warning identifies dropped, cycled, or fallback output.

Stable link: /guide/errors#band-label-margin-overflow

coord-tessellation-cap

Code + severity: coord-tessellation-cap · warning

What failed: A render step could not use every requested row, value, or default exactly as supplied.

Why: Adaptive coordinate tessellation reached a deterministic depth/vertex cap and retained a bounded approximation.

Fix: Inspect the warning message for its path and count, then correct the named data, scale, or option.

Consequence (degraded): The chart rendered, but the warning identifies dropped, cycled, or fallback output.

Stable link: /guide/errors#coord-tessellation-cap

coord-invalid-geometry

Code + severity: coord-invalid-geometry · warning

What failed: A render step could not use every requested row, value, or default exactly as supplied.

Why: Path vertices outside a coordinate transform's domain were removed without bridging the remaining finite runs.

Fix: Inspect the warning message for its path and count, then correct the named data, scale, or option.

Consequence (degraded): The chart rendered, but the warning identifies dropped, cycled, or fallback output.

Stable link: /guide/errors#coord-invalid-geometry

coord-fixed-degraded

Code + severity: coord-fixed-degraded · warning

What failed: A render step could not use every requested row, value, or default exactly as supplied.

Why: A fixed-aspect data rectangle is below the documented readable minimum; the ratio remains exact and minor furniture is removed.

Fix: Inspect the warning message for its path and count, then correct the named data, scale, or option.

Consequence (degraded): The chart rendered, but the warning identifies dropped, cycled, or fallback output.

Stable link: /guide/errors#coord-fixed-degraded

abline-scale-unsupported

Code + severity: abline-scale-unsupported · warning

What failed: A render step could not use every requested row, value, or default exactly as supplied.

Why: geom_abline needs continuous x and y scales to clip y = intercept + slope · x; the layer is skipped on band axes.

Fix: Inspect the warning message for its path and count, then correct the named data, scale, or option.

Consequence (degraded): The chart rendered, but the warning identifies dropped, cycled, or fallback output.

Stable link: /guide/errors#abline-scale-unsupported

function-domain-missing

Code + severity: function-domain-missing · warning

What failed: A render step could not use every requested row, value, or default exactly as supplied.

Why: geom/stat function could not resolve an x evaluation domain (no xlim, mapped x, or peer layer domain).

Fix: Inspect the warning message for its path and count, then correct the named data, scale, or option.

Consequence (degraded): The chart rendered, but the warning identifies dropped, cycled, or fallback output.

Stable link: /guide/errors#function-domain-missing

function-fun-missing

Code + severity: function-fun-missing · warning

What failed: A render step could not use every requested row, value, or default exactly as supplied.

Why: geom/stat function is missing the required params.fun registry function name.

Fix: Inspect the warning message for its path and count, then correct the named data, scale, or option.

Consequence (degraded): The chart rendered, but the warning identifies dropped, cycled, or fallback output.

Stable link: /guide/errors#function-fun-missing

function-fun-unknown

Code + severity: function-fun-unknown · warning

What failed: A render step could not use every requested row, value, or default exactly as supplied.

Why: geom/stat function named an unknown params.fun registry function.

Fix: Inspect the warning message for its path and count, then correct the named data, scale, or option.

Consequence (degraded): The chart rendered, but the warning identifies dropped, cycled, or fallback output.

Stable link: /guide/errors#function-fun-unknown

hex-band-scale

Code + severity: hex-band-scale · warning

What failed: A render step could not use every requested row, value, or default exactly as supplied.

Why: geom_hex needs continuous x and y scales for hexagonal binning; the layer is skipped on band axes.

Fix: Inspect the warning message for its path and count, then correct the named data, scale, or option.

Consequence (degraded): The chart rendered, but the warning identifies dropped, cycled, or fallback output.

Stable link: /guide/errors#hex-band-scale

hex-missing-size

Code + severity: hex-missing-size · warning

What failed: A render step could not use every requested row, value, or default exactly as supplied.

Why: geom_hex is missing per-cell width/height from bin_hex (identity or incomplete frame); the layer is skipped.

Fix: Inspect the warning message for its path and count, then correct the named data, scale, or option.

Consequence (degraded): The chart rendered, but the warning identifies dropped, cycled, or fallback output.

Stable link: /guide/errors#hex-missing-size

ydensity-group-dropped

Code + severity: ydensity-group-dropped · warning

What failed: A render step could not use every requested row, value, or default exactly as supplied.

Why: geom_violin needs at least two data points per group to estimate a density; smaller groups are dropped.

Fix: Inspect the warning message for its path and count, then correct the named data, scale, or option.

Consequence (degraded): The chart rendered, but the warning identifies dropped, cycled, or fallback output.

Stable link: /guide/errors#ydensity-group-dropped

Interaction diagnostics (@ggsvelte/svelte)

Each entry answers what failed, why, how to recover safely, and whether output was blocked or degraded.

INTERACTION_INTERVAL_FACET_UNSUPPORTED

Code + severity: INTERACTION_INTERVAL_FACET_UNSUPPORTED · warning

What failed: The zoom interaction contract could not be applied as requested.

Why: Brush zoom currently requires one unfaceted panel.

Fix: Remove the facet; Use faceted interval selection; Zoom a linked detail view

Consequence (degraded): The chart remains rendered, but the affected interaction is disabled or reduced.

Stable link: /guide/errors#interaction-interval-facet-unsupported

INTERACTION_INVALID_MAX_DISTANCE

Code + severity: INTERACTION_INVALID_MAX_DISTANCE · error

What failed: The inspect.maxDistance interaction contract could not be applied as requested.

Why: inspect.maxDistance must be a finite non-negative CSS-pixel distance.

Fix: Use a finite number greater than or equal to zero

Consequence (degraded): The chart remains rendered, but the affected interaction is disabled or reduced.

Stable link: /guide/errors#interaction-invalid-max-distance

INTERACTION_POINT_REQUIRES_KEY

Code + severity: INTERACTION_POINT_REQUIRES_KEY · warning

What failed: The key interaction contract could not be applied as requested.

Why: Durable point selection requires a stable key field or accessor.

Fix: Pass key="id"; Pass a stable key accessor

Consequence (degraded): The chart remains rendered, but the affected interaction is disabled or reduced.

Stable link: /guide/errors#interaction-point-requires-key

INTERACTION_INTERVAL_PRESET_REQUIRES_KEY

Code + severity: INTERACTION_INTERVAL_PRESET_REQUIRES_KEY · warning

What failed: The key interaction contract could not be applied as requested.

Why: Coordinated interval presets (union, cross-panel) require a stable key field or accessor; without one they combine no rows.

Fix: Pass key="id"; Pass a stable key accessor

Consequence (degraded): The chart remains rendered, but the affected interaction is disabled or reduced.

Stable link: /guide/errors#interaction-interval-preset-requires-key

INTERACTION_INVALID_KEY

Code + severity: INTERACTION_INVALID_KEY · error

What failed: The key interaction contract could not be applied as requested.

Why: A key accessor returned null, undefined, or a non-PropertyKey value.

Fix: Return a stable string, number, or symbol for every row

Consequence (degraded): The chart remains rendered, but the affected interaction is disabled or reduced.

Stable link: /guide/errors#interaction-invalid-key

INTERACTION_DUPLICATE_KEY

Code + severity: INTERACTION_DUPLICATE_KEY · error

What failed: The key interaction contract could not be applied as requested.

Why: The key accessor returned a duplicate value; durable interaction is disabled for that value.

Fix: Use a field that uniquely identifies each source row

Consequence (degraded): The chart remains rendered, but the affected interaction is disabled or reduced.

Stable link: /guide/errors#interaction-duplicate-key

INTERACTION_UNSTABLE_KEY

Code + severity: INTERACTION_UNSTABLE_KEY · error

What failed: The key interaction contract could not be applied as requested.

Why: The key accessor returned a different value for the same source row.

Fix: Return an immutable field that uniquely identifies each row

Consequence (degraded): The chart remains rendered, but the affected interaction is disabled or reduced.

Stable link: /guide/errors#interaction-unstable-key

INTERACTION_MISSING_LINEAGE

Code + severity: INTERACTION_MISSING_LINEAGE · warning

What failed: The layers interaction contract could not be applied as requested.

Why: A synthetic or aggregate mark did not expose source-row lineage.

Fix: Use a stat that preserves source-row lineage

Consequence (degraded): The chart remains rendered, but the affected interaction is disabled or reduced.

Stable link: /guide/errors#interaction-missing-lineage

INTERACTION_LEGEND_REQUIRES_KEY

Code + severity: INTERACTION_LEGEND_REQUIRES_KEY · warning

What failed: The key interaction contract could not be applied as requested.

Why: Legend focus requires stable row keys so encoded legend values never become identities.

Fix: Pass key="id"; Pass a stable key accessor

Consequence (degraded): The chart remains rendered, but the affected interaction is disabled or reduced.

Stable link: /guide/errors#interaction-legend-requires-key

INTERACTION_LEGEND_DISCRETE_ONLY

Code + severity: INTERACTION_LEGEND_DISCRETE_ONLY · advisory

What failed: The legendFocus interaction contract could not be applied as requested.

Why: Legend focus currently applies to discrete color and fill legends; continuous ramps remain static.

Fix: Use a discrete color or fill mapping; Keep the continuous ramp static

Consequence (advisory): The chart remains available; review the ignored or inferred interaction behavior.

Stable link: /guide/errors#interaction-legend-discrete-only

INTERACTION_INTERVAL_SCALE_UNSUPPORTED

Code + severity: INTERACTION_INTERVAL_SCALE_UNSUPPORTED · warning

What failed: The scales interaction contract could not be applied as requested.

Why: Interval domains and brush zoom require continuous linear, log, or time scales.

Fix: Use a continuous positional scale; Use point inspection for band data

Consequence (degraded): The chart remains rendered, but the affected interaction is disabled or reduced.

Stable link: /guide/errors#interaction-interval-scale-unsupported

INTERACTION_TOOL_UNAVAILABLE

Code + severity: INTERACTION_TOOL_UNAVAILABLE · warning

What failed: The tool interaction contract could not be applied as requested.

Why: The requested interaction tool is unavailable for the enabled capabilities.

Fix: Enable the matching capability; Choose an available interaction tool

Consequence (degraded): The chart remains rendered, but the affected interaction is disabled or reduced.

Stable link: /guide/errors#interaction-tool-unavailable

Minimal illustration — copy only the relevant fragment:

<GGPlot
  data={rows}
  aes={{ x: "weight", y: "economy" }}
  inspect={true}
  tool="inspect"
/>

INTERACTION_SCOPE_WITHOUT_CONTROLLER

Code + severity: INTERACTION_SCOPE_WITHOUT_CONTROLLER · advisory

What failed: The interactionScope interaction contract could not be applied as requested.

Why: interactionScope is ignored without an interaction controller; chart-local scope is derived from key and aes.

Fix: Pass interaction={createPlotInteraction()} to control this plot; Remove interactionScope from uncontrolled plots

Consequence (advisory): The chart remains available; review the ignored or inferred interaction behavior.

Stable link: /guide/errors#interaction-scope-without-controller

INTERACTION_HANDLER_WITHOUT_CAPABILITY

Code + severity: INTERACTION_HANDLER_WITHOUT_CAPABILITY · advisory

What failed: The oninspect / onselect / onzoom / onlegendfocus / onlegendfilter interaction contract could not be applied as requested.

Why: An interaction handler is set but its capability prop is not enabled, so the handler never fires.

Fix: Enable the matching capability prop (for example select for onselect); Remove the unused handler

Consequence (advisory): The chart remains available; review the ignored or inferred interaction behavior.

Stable link: /guide/errors#interaction-handler-without-capability

INTERACTION_INSPECT_X_ON_COL

Code + severity: INTERACTION_INSPECT_X_ON_COL · advisory

What failed: The inspect.mode interaction contract could not be applied as requested.

Why: inspect.mode draws a vertical guide through column marks; columns already encode x as a filled band, so the guide cuts the bar body and rarely adds information.

Fix: Use inspect={{ mode: "exact" }} (or leave mode as "auto") for GeomCol; Prefer muteSiblings for sibling de-emphasis instead of an axis guide

Consequence (advisory): The chart remains available; review the ignored or inferred interaction behavior.

Stable link: /guide/errors#interaction-inspect-x-on-col

Minimal illustration — copy only the relevant fragment:

<GGPlot data={rows} aes={{ x: "group", y: "amount" }} inspect={{ mode: "exact" }}>
  <GeomCol />
</GGPlot>

INTERACTION_INSPECT_X_ON_BAR

Code + severity: INTERACTION_INSPECT_X_ON_BAR · advisory

What failed: The inspect.mode interaction contract could not be applied as requested.

Why: inspect.mode draws a vertical guide through bar marks; bars already encode the band axis as a filled region, so the guide cuts the bar body and rarely adds information.

Fix: Use inspect={{ mode: "exact" }} (or leave mode as "auto") for GeomBar; Prefer muteSiblings for sibling de-emphasis instead of an axis guide

Consequence (advisory): The chart remains available; review the ignored or inferred interaction behavior.

Stable link: /guide/errors#interaction-inspect-x-on-bar

INTERACTION_INSPECT_X_BISECTS_COL_LABELS

Code + severity: INTERACTION_INSPECT_X_BISECTS_COL_LABELS · warning

What failed: The inspect.mode interaction contract could not be applied as requested.

Why: inspect.mode draws a vertical guide through GeomCol marks that also carry GeomText/GeomLabel values; the guide bisects the on-bar totals and makes them hard to read.

Fix: Use inspect={{ mode: "exact" }} (or leave mode as "auto") when columns have value labels; Keep value labels; drop the x/xy guide rather than dropping the labels

Consequence (degraded): The chart remains rendered, but the affected interaction is disabled or reduced.

Stable link: /guide/errors#interaction-inspect-x-bisects-col-labels

Minimal illustration — copy only the relevant fragment:

<GGPlot data={rows} aes={{ x: "group", y: "amount" }} inspect={{ mode: "exact" }}>
  <GeomCol />
  <GeomText aes={{ label: "label" }} dy={-8} />
</GGPlot>

INTERACTION_INSPECT_X_BISECTS_BAR_LABELS

Code + severity: INTERACTION_INSPECT_X_BISECTS_BAR_LABELS · warning

What failed: The inspect.mode interaction contract could not be applied as requested.

Why: inspect.mode draws a vertical guide through GeomBar marks that also carry GeomText/GeomLabel values; the guide bisects the on-bar totals and makes them hard to read.

Fix: Use inspect={{ mode: "exact" }} (or leave mode as "auto") when bars have value labels; Keep value labels; drop the x/xy guide rather than dropping the labels

Consequence (degraded): The chart remains rendered, but the affected interaction is disabled or reduced.

Stable link: /guide/errors#interaction-inspect-x-bisects-bar-labels

CLI diagnostics (ggsvelte-render)

SVG is written only to stdout; JSON Lines diagnostics are written only to stderr. Exit 1 means rendering failed, exit 2 means usage/input failed, and exit 3 means spec validation failed.

usage

Code + severity: usage · error

What failed: ggsvelte-render stopped with exit 2 and wrote this JSON Line to stderr.

Why: Bad flags or arguments (exit 2). --help shows usage.

Fix: Run ggsvelte-render --help, then remove unsupported or conflicting arguments.

Consequence (blocked): No successful SVG is available on stdout for this invocation.

Stable link: /guide/errors#usage

unreadable-input

Code + severity: unreadable-input · error

What failed: ggsvelte-render stopped with exit 2 and wrote this JSON Line to stderr.

Why: The spec/data file (or stdin) could not be read (exit 2).

Fix: Check the file path and permissions, or pipe readable JSON on stdin.

Consequence (blocked): No successful SVG is available on stdout for this invocation.

Stable link: /guide/errors#unreadable-input

invalid-json

Code + severity: invalid-json · error

What failed: ggsvelte-render stopped with exit 2 and wrote this JSON Line to stderr.

Why: The spec or data file is not valid JSON (exit 2).

Fix: Correct the JSON syntax before running the command again.

Consequence (blocked): No successful SVG is available on stdout for this invocation.

Stable link: /guide/errors#invalid-json

Minimal illustration — copy only the relevant fragment:

printf '%s\n' '{"data":{"values":[{"x":1,"y":2}]},"layers":[{"geom":"point","aes":{"x":{"field":"x"},"y":{"field":"y"}}}]}' \
  | ggsvelte-render > chart.svg

invalid-data-file

Code + severity: invalid-data-file · error

What failed: ggsvelte-render stopped with exit 2 and wrote this JSON Line to stderr.

Why: --data must be a JSON object mapping dataset names to inline data (exit 2).

Fix: Make --data point to a JSON object whose keys are dataset names.

Consequence (blocked): No successful SVG is available on stdout for this invocation.

Stable link: /guide/errors#invalid-data-file

max-marks-exceeded — cli

Code + severity: max-marks-exceeded · error

What failed: ggsvelte-render stopped with exit 1 and wrote this JSON Line to stderr.

Why: The plot renders more marks than --max-marks allows (exit 1).

Fix: Reduce the data or deliberately raise --max-marks after checking output cost.

Consequence (blocked): No successful SVG is available on stdout for this invocation.

Stable link: /guide/errors#max-marks-exceeded-cli

internal

Code + severity: internal · error

What failed: ggsvelte-render stopped with exit 1 and wrote this JSON Line to stderr.

Why: An unexpected internal error (exit 1). Please report it.

Fix: Capture stderr and report the reproducible command, versions, and input shape.

Consequence (blocked): No successful SVG is available on stdout for this invocation.

Stable link: /guide/errors#internal