| Using inside filter conditions | Filter silently fails | Use with the alias from |
| Omitting | Visual calculations may break | Always include |
| Reusing visual/filter names | Unpredictable behavior | Generate unique IDs |
| Setting to invalid string | Visual renders as error box | Run powerbi-report-author catalog describe <type>
powerbi-report-author catalog list
|
| Wrong role name for visual type | Field is ignored; visual blank | Match role names from powerbi-report-author catalog describe <type>
|
| Mixing and types | Query fails; visual error | Columns use , measures use |
| Forgetting to add page to | Page invisible | Add to array |
| Booleans without correct format | Wrong type | / (no suffix, unquoted in Value) |
| Numbers without type suffix | Type mismatch | for decimals, for integers |
| Editing version | PBI Desktop may reject | Preserve existing version |
| Stringified JSON in | Textbox shows nothing | is a native JSON array |
| Using textbox as a thin line/divider | Renders ~24px tall regardless of | Use a visual (rectangle) instead — shapes respect small dimensions |
| as sibling of | Schema validation error in PBI Desktop | Must be inside object, as sibling of |
| Using with dimension columns and measures all in | Headers render but no data rows even when DAX confirms data exists | Use ; put dimensions in and measures in |
| Using PowerShell to edit visual JSON | Property reordering, nesting depth truncation ( default is 2) | Use Node.js for JSON manipulation, or always pass and verify structure |
| Using regex or string replacement to modify JSON files | Corrupts nesting structure — properties end up inside sibling values, braces misalign | Read file → → modify object → → write back. Or use the tool with exact old/new string matching |
| without a selector on single-series charts | Bars/columns invisible despite data in tooltips | Use for a base color without a selector; requires a selector |
| Using on multi-series charts | All series/categories get the same color — no visual differentiation | Use theme for consistent palette across visuals, or with selectors for per-series overrides — see color-strategy.md § Color Strategy Quick Reference |
| Clustered bar/column chart colors collapse into one legend color | The visual has a Series role but all bars and legend markers share the same hue | Use per-series selectors or a theme palette; do not use on clustered charts |
| Relying on theme alone for cross-visual measure consistency | Same measure gets different colors on different visuals (index-based assignment varies with projection order) | Maintain a measure→color mapping and apply explicit / per visual — see color-strategy.md § Cross-Visual Measure-Color Consistency |
| Using for explicit per-measure with metadata selectors | Colors silently resolve to white or black instead of expected palette color | Use hex values for explicit color assignments with metadata selectors — is unreliable in this context |
| Choosing bar/series colors without checking background contrast | Bars or lines invisible against page/card background (e.g., white bars on white canvas) | Always pick saturated, mid-to-dark hues that contrast with the page and VCO background colors |
| property on page-level | Schema error — page only supports , , | Only VCO (on visuals) has ; page background is always visible |
| Copying property names from doc examples without verifying | Warnings or silent failures — property names vary by visual type | Always run powerbi-report-author formatting describe-object <type> <object>
|
| Guessing which object a property belongs to | Wasted calls checking wrong objects one by one | Run powerbi-report-author formatting search <type> <regex>
|
| Formatting property has no effect (no error) | Setting on cardVisual outline without an id selector — validates but renders unchanged | Check powerbi-report-author formatting describe-object <type> <object>
|
| Using on a single-value card | Properties validate but have no visible effect — only renders on multi-value cards (2+ measures in Data) | Use // with selector for single-value cards. For multi-value cards, controls per-callout tile styling — see card.md § Multi-Value Formatting |
| Using as the role for | Cards render empty — PBI Desktop cannot resolve the binding. Validator reports and Required role "Data" missing
| 's only data role is . is the legacy visual's role name — never carry it over. Always verify role names with powerbi-report-author catalog describe cardVisual
|
| Creating separate single-value instances for multiple related KPIs | Wastes canvas space and misuses the visual type — natively supports multiple projections in one tile | Default to one multi-value with all measures as projections when ≥2 related KPIs are requested. Only use separate cards when per-card styling differences are required — see card.md § When to Consolidate vs. Keep Separate |
| Adding multiple fields to button slicer Values or Label roles | Slicer breaks or shows unexpected results — each role accepts only 1 field | Put one field in Values, one in Label; additional fields go to Tooltips |
| Looking at on other visuals to understand slicer selections | Slicer selections live only inside the slicer's own via + . Always read first when modifying slicers | |
| Creating an image visual without prompting for the source type | Wrong visual structure — URL vs local file vs data field each have different schemas and expression types | Always ask the user for the image source (local file / URL / data field) before creating the visual — see image.md § Source Types Overview |
| Creating a data-bound image visual with a field that lacks | Visual renders blank or error | Warn the user first — the visual will render blank without . Present alternatives (other ImageUrl fields, local file, URL) and confirm before creating — see image.md § Select from data |
| Placing background image on page canvas instead of visual plot area | User asks for "background image" alongside a visual (e.g., "column chart with background image") but image is placed on page.json → objects.background
| When a background image is requested in the context of a specific visual, default to . Only use page-level when the user explicitly says "page background" / "canvas background" or no visual context exists — see image.md § Plot Area Background Image |
| Creating a visual | Legacy multi-row card — deprecated; powerbi-report-author validate
PBIR_VISUAL_TYPE_DEPRECATED
| Always use . For multiple KPIs, use a single multi-value with all measures as projections in the role — see card.md |
| Using or instead of for map visuals | Legacy Bing Maps visuals — deprecated and must not be created; powerbi-report-author validate
PBIR_VISUAL_TYPE_DEPRECATED
| Always use — see map.md. If the map fails to render or geocode, debug the fields, try alternative geographic columns/coordinates, or ask the user — do not silently substitute a non-map visual without consulting the user first |
Creating / without columnAdjustment: growToFit
| Columns shrink-wrap to content, leaving unused whitespace | Always set columnHeaders.columnAdjustment
|
| Custom table/matrix row colors with no effect (white background) | Default style preset overrides -level / | Set VCO to on every / with custom colors — see table.md § Style Presets |
| Table cells white despite dark VCO background | visualContainerObjects.background
| Set dark colors in objects.values.backColorPrimary/Secondary
objects.columnHeaders.backColor
|
| Dark theme applied but cards/tables/slicers still white | Dark mode triggers every formatting trap simultaneously | Follow the full re-theming.md § Dark Mode Authoring Checklist — covers stylePreset, fillCustom+id selector, objects vs VCO, and contrast audit |
| Theme JSON changes do not appear after Desktop reload | Desktop caches theme files by file name | Rename the theme JSON with a small random suffix, update the theme registration in , then reload; otherwise close and reopen Desktop |
| Placing inside or at root of | Schema validation error; sort silently ignored — chart falls back to alphabetical | is a property of — use visual.query.sortDefinition
visualConfiguration/2.2.0
|
| Container shape fill doesn't match reference | Text invisible or wrong background color | Match the fill color and transparency to the reference image. If the page background already provides the color, skip the shape entirely. If the shape must be invisible, verify text color still contrasts with the page canvas — see shape.md § Container Shapes |
| Shape text invisible after re-theme | Shape object has no explicit — text inherits theme foreground, but when is a light color (e.g., white pill/button) on a light page canvas, inherited dark foreground may not render or the fill blends with canvas making text vanish | Always set explicit on shape objects (in the { selector: { id: "default" } }
|
| Enabling on data with zero or negative values | PBI Desktop silently falls back to linear scale with a warning — log of zero/negative is undefined | Warn the user before applying. Use to present alternatives (filter negatives, switch measure, use ). Apply only after the user resolves negative values or confirms all bound values are positive — see cartesian.md § Log Scale |
| Changing theme without sweeping inline overrides | Old colors remain on shapes, page backgrounds, nav buttons, textboxes — theme-only change has no effect on hardcoded hex values at Priority 2 in the cascade | When the report has per-visual color overrides, follow re-theming.md § Re-theming Workflow Steps 0–3: build a color mapping, update theme JSON, then bulk-sweep files for old hex values before reload |
| Changing only in theme without sweeping | Shapes, accent bars, nav button borders retain old accent colors — they use hardcoded Literal hex from the old array, not references | Sweep ALL old hex values across files. Even same-polarity "just change the accent/data colors" requests need the full sweep — shapes and nav elements commonly hardcode as accent fills/outlines. |