Related: Data Visualizer import troubleshooting | dataset format guide | template download
Data Visualizer import errors – top causes and exact fixes
If Visio Data Visualizer rejects a dataset, the cause is almost always structural: separators, headers, IDs, or hidden characters. This guide gives a fast checklist, a symptom map, and fixes that keep imports stable.
Fast triage – 7 checks that fix most imports
Run these checks in order. The goal is simple: make the dataset strict enough that Visio can import it every time.
- Confirm the file is TSV (tab separated values), not CSV (comma separated values).
- Confirm the header row matches your template exactly (spelling, order, and capitalization).
- Delete blank lines (including a single empty row at the bottom).
- Verify Process Step IDs are unique and stable.
- Verify Next Step IDs point to real Step IDs (no missing references).
- Verify branching syntax: multiple Next Step IDs are comma separated with no spaces.
- Remove hidden characters (line breaks inside cells, smart quotes, non-printing characters).
A fast prevention move: import a 10-step dataset first, then change 1 row and re-import. If it round trips cleanly, scaling becomes predictable.
Symptom map – what the failure usually means
| Symptom | Likely cause | Fix |
|---|---|---|
| Import fails immediately | Not TSV, header mismatch, blank line, or a cell contains a hidden line break | Re-export as TSV, re-check headers, delete blank rows, remove line breaks inside cells |
| Imports but connectors are missing | Next Step IDs do not match Step IDs exactly | Normalize IDs, then verify every Next Step ID exists as a Process Step ID |
| Imports but swimlanes look wrong | Function values are inconsistent (different spellings for the same lane) | Standardize Function values (single naming convention) before scaling |
| Imports but layout is chaotic | Valid data, but poor grouping (Function and Phase values are too fragmented) | Reduce category sprawl (merge lane names, merge phases, keep names short) |
Common causes – the exact fixes
1) CSV instead of TSV
Data Visualizer expects tab separators. If a file is comma delimited, Visio may treat the entire line as 1 field.
Fix: export or save as TSV. Then re-open the TSV and confirm columns split correctly.
2) Header row mismatch
The importer is strict about the header row. A single typo or changed column order can break the import.
Fix: start from a known-good template. Avoid hand-typing column names.
3) Blank lines and trailing rows
A common failure is an empty row at the bottom of the file. The dataset looks complete, but the importer sees a blank record.
Fix: delete blank rows and re-export. Also check for accidental blank lines after copy and paste.
4) Duplicate or unstable Step IDs
Step IDs behave like primary keys. If IDs are duplicated, reused, or changed between versions, connectors and refresh logic break.
Fix: use a stable ID scheme (010,020,030) and never reuse an ID for a different step.
5) Next Step references that do not exist
If a Next Step ID points to an ID that is missing, Visio cannot build a consistent flow.
Fix: run a quick reference check. Every value in Next Step ID must appear in Process Step ID.
6) Branching syntax with spaces
Multiple next steps must be represented as comma separated IDs with no spaces.
Correct: 030,040,050
Wrong: 030, 040, 050
7) Hidden line breaks inside cells
Copying shape text into Excel can introduce line breaks inside a cell. Visio then interprets the TSV as malformed.
Fix: remove line breaks and non-printing characters. In Excel, search for line breaks and replace with a space.
Pre-import validation checklist (copy/paste)
Run this checklist before importing. It reduces the odds of a failed import and keeps refresh cycles clean.
- TSV file (tabs), not CSV (commas)
- No blank lines anywhere in the file
- Header row matches the template exactly
- Every Process Step ID is unique
- Every Next Step ID points to an existing Process Step ID
- End shapes have a blank Next Step ID
- Comma lists have no spaces (030,040 not 030, 040)
- No leading or trailing spaces in key fields (IDs, Shape Type, Function)
- No line breaks inside cells
Want the fastest path to a clean dataset? Start with Lite to validate the import workflow, then move to Standard when the dataset needs to scale.
FAQ
Does Data Visualizer accept CSV?
Data Visualizer expects a tab separated values (TSV) dataset. If a CSV is used, fields may not parse as intended. The safest approach is to start from a known-good TSV template.
Why do Step IDs matter so much?
Step IDs function like unique keys. They define shape identity and they are how connectors are built using Next Step IDs. If IDs are duplicated or change between versions, refresh and connector logic becomes unreliable.
What does “Function” mean in the dataset?
Function is the swimlane field. In a swimlane diagram, it defines which lane each step belongs to. If Function values drift (HR vs Human Resources), Visio treats them as different lanes.
Where do the exact TSV rules live?
The rules are summarized in the dataset format guide, and the simplest path is to use the template download.
What if the import succeeds but the diagram looks messy?
That is usually a classification issue, not a formatting issue. Consolidate lane names (Function), reduce Phase sprawl, and keep step descriptions short. Then re-import. The dataset can be correct while the view is noisy.
