ds-ref-pitfalls

name

ds-ref-pitfalls

description

Splunk Dashboard Studio cross-skill pitfalls matrix — the "if X is wrong, look here" first-stop reference. Maps common symptoms (panel renders empty, axes flipped, sparklines only on row 1, multiselect breaks IN(), threshold colours land in wrong bucket, validator rejects schema, drilldown payload missing) to the per-viz / interactivity / reference skill that owns the fix. Spans viz, interactivity, and schema concerns. Use when the user reports a Splunk Dashboard Studio panel that doesn't render correctly, when validating a JSON-rejected dashboard, or as the first stop for "why is X not working" debugging questions.

ds-ref-pitfalls — cross-skill traps matrix

The "if X is wrong, look here" first-stop. Every row points to the per-viz / interactivity / reference skill that owns the full fix.

Empty / broken panels

Symptom	Likely cause	Fix lives in
splunk.bar renders with axes flipped, no bars	Added "x": / "y": DOS options (those are scatter/bubble-only).	ds-viz-bar GOTCHAS #2
splunk.column renders no bars, flipped	Same trap as above.	ds-viz-column GOTCHAS #3
splunk.bar renders bars in random order	SPL didn't `	sort - `.
splunk.line series silently disappears	Field name starts with _ (other than _time).	ds-viz-line GOTCHAS #8
splunk.line log scale ate values	yAxisScale: "log" rejects ≤ 0; set yAxisMin: "1".	ds-viz-line GOTCHAS #4
splunk.area second / third tier flatlines	Largest series at top of stack — re-sort SPL.	ds-viz-area GOTCHAS #3
splunk.pie slice order random	Pie has no sort; `	sort - ` in SPL.
splunk.pie collapseThreshold collapses everything	It's a fraction (0–1), not a percent. 0.05 = 5%.	ds-viz-pie GOTCHAS #2
splunk.map empty basemap, no points	Bubble layer needs `	geostats, NOT
splunk.map choropleth all "no data" colour	Wrong key shape: geo_countries keys on full names (United States), geo://default/world keys on ISO-2 (US).	ds-viz-map GOTCHAS #3
splunk.map choropleth dies with Unexpected token 'N', "Null" is not valid JSON	tostring(NULL) → "Null". Add `	where isnotnull(geom)BEFOREtostring`.
splunk.map second layer disappears	Multi-layer marker + bubble (or + choropleth) is unreliable. Use separate panels.	ds-viz-map GOTCHAS #16
splunk.map bubble dataColors does nothing	Bubble uses > dataValues, NOT `> primary	seriesByName(...)`.
splunk.choropleth.svg no fills	Path IDs case-sensitive; <rect> / <circle> not picked up — convert to <path>.	ds-viz-choropleth-svg Do/Don't
splunk.singlevalueicon icon missing	Icon URL is per-instance — re-pick on the target Splunk via editor.	ds-viz-singlevalueicon Two valid forms
splunk.singlevalueicon Title / Description don't show	Doesn't support panel title/description. Use sibling splunk.markdown.	ds-viz-singlevalueicon OPTIONS
splunk.timeline category rejected	Must be DOS string `> primary	seriesByName('host'), not bare "host"`.
splunk.sankey empty	Field names must be lowercase source / target / value — exactly.	ds-viz-sankey Do/Don't
splunk.events field summary rail empty	Needs secondary dataSources.fieldsummary (ds.chain extending primary with `	fieldsummary`).
splunk.markdown table renders as raw `	`-text	GFM pipe-tables not supported. Use bullet lists with bold field labels.

Sparkline / table issues

Symptom	Likely cause	Fix lives in
Sparkline column renders only on row 1	`eval x="1,2,3"	makemvonly types row 1 as mv. Use
Sparkline colours don't apply	Data density too low — mvcount(trend_cpu) ~ 3 means one datapoint. Widen synthetic time range.	ds-viz-table GOTCHAS #12 + SPARKLINE-DATA.md
Per-column sparkline colour ignored	tableFormat.sparklineColors distributes per-row, not per-column. Use columnFormat.<col>.sparklineColors.	ds-viz-table GOTCHAS #10
Heatmap row tinting wrong rows red	Half-step thresholds (1.5, 2.5) so integer ranks land cleanly.	ds-viz-table PATTERNS #7
_color_rank column shows in rendered table	Missing showInternalFields: false.	ds-viz-table GOTCHAS #1
Header unreadable in light theme	Hardcoded #0B0C0E headerBackgroundColor. Don't set — let theme defaults track.	ds-viz-table GOTCHAS #5

Threshold / RAG colour bugs

Symptom	Likely cause	Fix lives in
Boundary value 60 lands in red instead of amber	[{to:70}, {from:60, to:80}, {from:70}] — overlap, top-down + first-match wins.	ds-viz-singlevalue GOTCHAS #3
Middle bucket never seen on render	Demo data only hits two buckets. Use 20 / 60 / 95 against thresholds 60 / 80.	ds-viz-singlevalue Do/Don't
Whole-tile flips to dark, headline disappears	backgroundColor dynamic without locking majorColor.	ds-viz-singlevalue GOTCHAS #6
Trend doesn't auto-flip red/green	trendColor defaults to theme font colour. Drive with DOS expression.	ds-viz-singlevalue GOTCHAS #1
Choropleth empty area renders theme-grey	When showBaseLayer: false, set choroplethEmptyAreaColor explicitly.	ds-viz-map GOTCHAS #12
splunk.choropleth.svg areaColors: "#FF0000" paints every region the literal string	Must be DOS string with rangeValue / gradient.	ds-viz-choropleth-svg Do/Don't

Interactivity bugs

Symptom	Likely cause	Fix lives in
Multiselect into SPL IN() breaks on hyphens / spaces	Need `	sfilter:IN ($status
"All" sentinel in multiselect produces invalid SPL	Add OR ("$tok$" = "*") clause.	ds-int-tokens Quick recipes
Drilldown customUrl corrupted by & / ?	Missing `	u` filter on tokens in URL.
drilldown.linkToDashboard tokens not forwarded	tokens must be array of {token, value}, not string-keyed map.	ds-int-drilldowns Do/Don't
Receiving dashboard's input doesn't pick up forwarded value	linkToDashboard.token should be raw name, NO form. prefix.	ds-int-drilldowns Do/Don't
Visibility condition S0201 Syntax error: "web" at position 5	Wrapped token in quotes ("$selected_host$"). Use bare $selected_host$.	ds-int-visibility Do/Don't
Visibility condition S0201 Syntax error: "isSet"	isSet() is Cloud-only. Use $tok$ != "".	ds-int-visibility Do/Don't
visibility rejected with must NOT have additional properties	Visibility is under containerOptions, never panel root.	ds-int-visibility Do/Don't
Token shows literal $tok$ text in markdown panel	Token interpolation works in markdown — wrap in inline code $tok$ to avoid * / _ collisions.	ds-viz-markdown Do/Don't
Dashboard panel doesn't update on input change	Token name typo. Cmd-F across JSON; must match exactly.	ds-int-tokens Debug ladder
Dynamic dropdown frozen / not refreshing	enableSmartSources: true missing on parent search.	ds-int-inputs Do/Don't
input.timerange schema error on save	defaultValue MUST be "-24h@h,now" string, NOT object.	ds-int-inputs Do/Don't
Tabbed dashboard panels missing	layoutId mismatch with layoutDefinitions key, OR layout.type set alongside layout.tabs.	ds-int-tabs Do/Don't
Hidden tab still costing search dispatch	Add containerOptions.visibility to gate searches inside hidden tabs.	ds-int-visibility Caveats

Schema rejections

Symptom	Likely cause	Fix lives in
seriesColors: must be array / must match pattern "^>.*"	CSV string "#aaa,#bbb" rejected. Use array ["#aaa", "#bbb"].	ds-viz-sankey Do/Don't, ds-viz-timeline GOTCHAS #3
dataSource name must match ^[A-Za-z0-9 \-_.]+$	, ( ) / > : in user-facing name field.	ds-ref-syntax name field rule
input.<id>.type: must be equal to one of the allowed values	Tried input.radio / input.number / input.date — only 5 types exist.	ds-int-inputs 5 flavours
must NOT have additional properties on multiselect	Tried valuePrefix / valueSuffix / delimiter — Studio v2 doesn't support. Use `	s` filter.
Validator rejects splunk.choropleth.map viz type	Doesn't exist. Use splunk.map with choropleth layer.	ds-viz-map Common confusions
fontSize: 11 (number) silently breaks panel	fontSize is an enum string: extraSmall, small, default, large, extraLarge. Never a number.	ds-viz-markdown, ds-couture rule 12
Markdown panel shows raw <span> / <div> tags	Studio strips all raw HTML. Use plain markdown (**bold**, headings) + fontColor/fontSize in options.	ds-viz-markdown, ds-couture rule 11
_time label stuck on x-axis despite "hiding" it	Wrong property: showXAxisTitle does NOT exist. Use xAxisTitleVisibility: "hide".	ds-viz-area, ds-viz-line, ds-viz-column
Choropleth "d is not iterable" error on Color tab	Context uses {type:"range", ranges:[...]} wrapper. Use a flat array instead.	ds-viz-choropleth-svg Do/Don't, ds-svg CANVAS-PATTERNS
Data sources show "Unnamed" in Studio picker	Missing options.name on ds.search. Every dataSource MUST have a human-readable name.	ds-create hard rule
columnGrouping: must match pattern schema error	Used "stacked" as columnGrouping value. That's stackMode, not columnGrouping. Valid: "auto", "overlay", or DOS string.	ds-viz-column Do/Don't
must NOT have additional properties on defaults block	defaults.visualizations.global.options is invalid. Only dataSources.global is supported. Leave defaults: {} or use only dataSources.global.	ds-couture rule 13, ds-int-defaults

Time axis traps

Symptom	Likely cause	Fix lives in
Area / line / column chart renders empty or shows no data points	_time converted to string via eval _time=strftime(...). Chart viz types require _time as epoch — string kills the x-axis.	ds-couture rule 5 clarification, ds-create hard rules
X-axis shows raw epoch numbers instead of formatted dates	Normal — Splunk auto-formats epoch _time on the x-axis. Do NOT manually format _time for charts.	ds-viz-area, ds-viz-line, ds-viz-column

Layout traps

Symptom	Likely cause	Fix lives in
Shape primitives (rectangle / ellipse / image) silently fail to render	Require layout.type: "absolute". Skipped on grid / tabs.	ds-viz-rectangle, ds-viz-ellipse, ds-viz-image
splunk.singlevalueicon falls back to plain singlevalue	Same: requires absolute layout.	ds-viz-singlevalueicon
KPI ring + singlevalue overlay shows ring on top	Z-order is structure array order. Earlier = behind.	ds-viz-rectangle PATTERNS, ds-viz-ellipse PATTERNS
Categorical Timeline bars collapse into mush	Half-width panel — needs full row (w: 1408).	ds-viz-timeline GOTCHAS #4
KPI tile bank looks like separate cards	backgroundColor: "transparent" on each tile + 4–8 px gap.	ds-viz-markergauge / ds-viz-fillergauge Do/Don't

Image & SVG

Symptom	Likely cause	Fix lives in
External image URL renders as placeholder	Domain must be on dashboards_image_allow_list. Splunk-bundled /en-US/static/... is always trusted.	ds-viz-image
External image URL doesn't render in PDF/PNG export	Only uploaded KV-store images render. Always upload for PDF.	ds-viz-image Do/Don't
App-bundled image "not found" after install	Image in wrong path. Must be appserver/static/images/, not root static/. Needs Splunk restart.	ds-viz-image §3
SVG choropleth no fills	<rect> / <circle> not picked up — only <path> with unique id.	ds-viz-choropleth-svg Do/Don't
Markdown fontFamily schema error	Only 7 fonts allowed: Splunk Platform Sans/Data Sans/Platform Mono, Arial, Helvetica, Times New Roman, Comic Sans MS. No custom fonts.	ds-viz-markdown §fontFamily
Markdown fontSize schema error	Only enum values: extraSmall, small, default, large, extraLarge. No numbers like "14" or "11".	ds-viz-markdown §fontSize
Markdown panel has scrollbar	Panel width or height too small for text at chosen fontSize. Heading text needs ~40px/line, body ~24px/line. Always oversize then tighten.	ds-viz-markdown Do/Don't

Performance

Symptom	Likely cause	Fix lives in
Searches hammer the indexer	Every ds.search should bind queryParameters.earliest / latest via defaults block, not per-search.	ds-int-defaults
Same SPL runs N times	Use ds.chain extending a single ds.search for variations.	ds-ref-syntax Base-search + chain pattern
Hidden panel still dispatches	Visibility-hidden panels skip dispatch; ensure containerOptions.visibility is set, not just display: none.	ds-int-visibility Caveats
resultLimit silently drops rows	Aggregate upstream with `	head N/

When to use this skill

• First stop for any "Splunk dashboard panel doesn't render correctly" ticket.
• Triage layer before opening per-viz GOTCHAS — points you at the right skill in 1 lookup.
• Cross-skill awareness — same symptom (e.g. "schema rejects CSV array") appears across sankey, timeline, ellipse, rectangle. This matrix shows the pattern.

See also

• ds-ref-design-principles — design-level antipatterns (rainbow on ordered data, pie >6 slices, KPI uniformity).
• ds-couture — visual-quality antipatterns the schema cannot catch: KPI uniformity (no anchor), unset canvas colour leaving Splunk-grey background, status colour without semantic intent, 12 panels in a uniform grid with no zones, sparkline omitted on count KPIs, rainbow on ordered axes. Run ds-couture Slop Test as a final pass; this skill catches config / schema bugs, ds-couture catches taste bugs.
• spl-gotchas (from splunk-spl plugin) — SPL-level pitfalls: case() default trap, spath output= not as, dotted-field quoting, unbounded searches that return wrong rows in dashboards.
• ds-ref-syntax — JSON envelope rules.
• Per-viz GOTCHAS.md files — full detail behind every entry above.