Troubleshooting

pbiviz Build Errors: 12 Common Fixes That Actually Work

· VizForge Team

TL;DR

The pbiviz CLI is Microsoft's official toolchain for packaging Power BI custom visuals. Its error messages are often unclear, and the fixes aren't documented in one place. This post consolidates the 12 most common pbiviz errors we see — UUID collisions, apiVersion mismatches, D3 version gotchas, null DataView crashes, silent packaging failures — with the exact fix for each. If you've hit an error mid-build, search for the message below and skip to the fix.

Power BI custom visuals ship via the pbiviz CLI (package powerbi-visuals-tools). The toolchain is solid but the errors are terse — a typical failure message is three lines long and assumes you know the internals. This reference collects the errors we've hit repeatedly over hundreds of builds, with working fixes.

1. 'pbiviz package' silently fails with no output

**Symptom:** `pbiviz package` exits 0, reports success, but no .pbiviz file appears in the dist/ folder.

**Cause:** The most common root cause is missing or invalid fields in pbiviz.json — specifically an empty `author.name` or `author.email`. Without these, the packager writes no file but doesn't error.

**Fix:** Open pbiviz.json and ensure both fields are populated:

pbiviz.json

{
  "visual": {
    "name": "MyVisual",
    "displayName": "My Visual",
    "guid": "MyVisual1234567890abcdef"
  },
  "author": {
    "name": "Your Name",
    "email": "you@company.com"
  },
  "apiVersion": "5.11.0"
}

2. 'Visual name contains invalid characters'

**Symptom:** `pbiviz new my-visual` fails with "name contains invalid characters."

**Cause:** pbiviz names must be only letters and numbers. Hyphens, underscores, and spaces are all rejected.

**Fix:** Rename to camelCase or PascalCase:

# Bad:  pbiviz new my-visual
# Bad:  pbiviz new my_visual
# Good:
pbiviz new myVisual
pbiviz new MyVisual

3. apiVersion mismatch warning on install

**Symptom:** After `npm install`, you see "apiVersion in pbiviz.json (5.3.0) does not match installed powerbi-visuals-api (5.11.0)."

**Cause:** The apiVersion field is a hint to the packager about which API your visual targets. pbiviz will auto-install the matching powerbi-visuals-api package, but the mismatch warning persists until you update pbiviz.json.

**Fix:** Edit pbiviz.json to match the installed version, or let pbiviz rewrite it:

# Let pbiviz update pbiviz.json to match the installed API:
pbiviz update
# Or manually set pbiviz.json "apiVersion": "5.11.0"

4. 'Duplicate GUID detected' when importing .pbiviz

**Symptom:** Power BI Desktop refuses to import a .pbiviz with "A visual with this GUID already exists."

**Cause:** Two visuals in the same report or the same organizational store can't share a GUID. The pbiviz.json's `guid` field must be unique.

**Fix:** Generate a fresh UUID (lowercase, no dashes in the stored form for historical compatibility):

# Windows PowerShell
[guid]::NewGuid().ToString("N")

# Or Node
node -e "console.log(require('crypto').randomUUID().replace(/-/g,''))"

5. D3 v5 vs v7 API incompatibility

**Symptom:** Generated visual throws runtime errors like `d3.scaleBand is not a function` or `d3.scaleLinear(...).range is not a function`.

**Cause:** Power BI custom visuals SDK historically ships with D3 v5. Many tutorials and third-party snippets assume D3 v7, where the scales API changed subtly (d3.scaleLinear().domain().range() chaining works on both, but some methods like d3.group, d3.flatGroup, and d3.extent behavior on signed numbers differ).

**Fix:** Always pin D3 explicitly in package.json and check which version ships with your pbiviz tools:

npm list d3
# For new visuals, prefer D3 v7 explicitly:
npm install d3@^7 @types/d3@^7

6. Visual crashes on empty DataView

**Symptom:** Visual renders fine in Developer mode, but crashes on an empty page (before user adds data) with `Cannot read property 'values' of undefined`.

**Cause:** The `update()` method is called on every interaction, including when the DataView is empty (e.g. before data is bound). Most tutorials don't handle this.

**Fix:** Make null/empty DataView the FIRST thing you check in update():

visual.ts

public update(options: VisualUpdateOptions) {
    const dv = options.dataViews?.[0];
    if (!dv || !dv.categorical || !dv.categorical.categories?.length) {
        // Clear the visual gracefully
        this.target.innerHTML = "";
        return;
    }

    // ...rest of update logic
}

7. Cross-filtering (SelectionManager) not working

**Symptom:** Clicking on your visual's elements doesn't filter other visuals on the Power BI page.

**Cause:** You instantiated `ISelectionManager` but forgot to register selection IDs on each mark, or you're rebuilding selection IDs on every update (which loses track of what's selected).

**Fix:** Build selection IDs once per data point (typically in a data-prep phase), store them on your d3 datum, and call `selectionManager.select(id)` in your click handler:

import powerbi from "powerbi-visuals-api";
import ISelectionId = powerbi.visuals.ISelectionId;
import ISelectionManager = powerbi.extensibility.ISelectionManager;

// In update():
const host = this.host;
const dataPoints = categories.values.map((v, i) => ({
    value: v,
    selectionId: host.createSelectionIdBuilder()
        .withCategory(categories, i)
        .createSelectionId(),
}));

// In click handler:
this.selection.on("click", (event, d) => {
    this.selectionManager.select(d.selectionId, event.ctrlKey);
});

8. Tooltip doesn't appear

**Symptom:** The default Power BI hover tooltip doesn't show over your visual's elements.

**Cause:** You need to register elements with the TooltipService explicitly — they're not auto-detected. Also ensure you have non-null tooltip text for each element.

**Fix:** Wire up tooltipService.addTooltip():

this.tooltipService.addTooltip(
    this.selection,
    (d) => [
        { header: d.value, displayName: "Amount", value: `${d.value}` }
    ],
    (d) => d.selectionId
);

9. Formatting pane updates don't persist

**Symptom:** User changes a color or toggle in the formatting pane, but the visual re-renders with the default.

**Cause:** You likely forgot to read from `dataView.metadata.objects` in update(). Formatting pane values live there.

**Fix:** Parse `dataView.metadata.objects` through DataViewObjectsParser (or manually) and use the parsed settings in every render:

import { dataViewObjectsParser } from "powerbi-visuals-utils-dataviewutils";

class VisualSettings extends dataViewObjectsParser.DataViewObjectsParser {
    color: { fill: string } = { fill: "#0078D4" };
}

public update(options: VisualUpdateOptions) {
    const settings = VisualSettings.parse<VisualSettings>(
        options.dataViews[0]
    );
    // use settings.color.fill for your fills
}

10. Certificate warning on Windows

**Symptom:** `pbiviz start` reports "The certificate for this server is invalid."

**Cause:** pbiviz's dev server self-signs a certificate on first run. Windows sometimes fails to trust it.

**Fix:** Re-generate and re-install the dev certificate. This warning is harmless if you only use `pbiviz package` (it doesn't need the cert); but if you use `pbiviz start` for live-reload dev, fix it once:

# From an elevated PowerShell:
pbiviz --install-cert
# Then restart Power BI Desktop

11. esbuild native binary rejected by Vercel / Next.js

**Symptom:** Deploying a Next.js app that bundles pbiviz-generated code, you hit `esbuild native binary could not be loaded.`

**Cause:** esbuild ships a native binary and must be externalized when used in a Next.js/Turbopack server context. Otherwise the bundler tries to bundle the native binary and the deploy fails.

**Fix:** Mark esbuild as external in next.config.ts:

next.config.ts

// next.config.ts
const nextConfig: NextConfig = {
  serverExternalPackages: ["esbuild"],
};

export default nextConfig;

12. Visual imports but doesn't appear in the Visualizations pane

**Symptom:** Power BI Desktop accepts the .pbiviz import without error, but the visual never shows up in the Visualizations pane.

**Cause:** The display name in pbiviz.json conflicts with an existing visual (from AppSource or a previously imported version), and Power BI silently hides the duplicate.

**Fix:** Set a distinctive display name in pbiviz.json and re-package:

pbiviz.json

{
  "visual": {
    "displayName": "My Sankey by Acme Corp",
    ...
  }
}

When to stop debugging and regenerate

If you're hitting multiple errors in a single build, sometimes the fastest fix is to regenerate the visual rather than patch errors one by one. pbiviz scaffolding drifts between versions, and inherited bugs from old templates are hard to find.

A clean regeneration of a working-reference visual takes 2 minutes. A fight against a cascade of template errors takes hours.

Skip pbiviz errors — generate with VizForge

Free plan: 3 visuals per month. AI handles pbiviz packaging, validation, and error recovery for you.

FAQ

Which pbiviz version should I target for new visuals in 2026?

powerbi-visuals-tools v7.x with apiVersion 5.11+ is the current baseline. It ships modern TypeScript, supports Formatting Model v2 (the new declarative formatting-pane API), and handles the Unified Framework visuals cleanly.

Do I need Visual Studio to develop Power BI custom visuals?

No. VS Code + Node.js is sufficient. The pbiviz CLI does all the TypeScript compilation and packaging; you just need any editor.

Can Power BI Service reject a .pbiviz that worked in Desktop?

Yes — Service enforces stricter sandbox rules. The most common rejection is for visuals that call fetch() to external URLs without declaring privileges. Add "Privileges" to capabilities.json and declare any external endpoints.

How do I publish a .pbiviz to AppSource?

AppSource certification is a separate multi-step process through Microsoft Partner Center. The visual must pass automated tests plus a manual review. Allow 4–8 weeks.

Can I update a .pbiviz after it's imported into a report?

Yes. Rebuild with a new version in pbiviz.json, import the new file in Power BI Desktop — it overwrites the previous visual in that report. Reports published to Service need to be re-published to pick up the update.

Related reading

VizForge documentation

Full reference on generating Power BI custom visuals with the VizForge AI pipeline, including environment setup and troubleshooting.

Visual catalog

Every visual type VizForge generates — from Sankey to Gantt — with data-shape references and example prompts.

Generate a visual without pbiviz errors

Skip the CLI entirely. Describe the visual you need; VizForge produces a validated .pbiviz ready to import.

Cite this article as:

VizForge. “pbiviz Build Errors: 12 Common Fixes That Actually Work.” April 23, 2026. https://vizforge.ai/blog/pbiviz-build-errors-common-fixes

Your next visual
ships in 4–10 min.

Sign up free. 5 credits to generate your first visuals on us. No credit card required.