Troubleshooting
This page lists common issues and practical fixes.
If you still need help after trying the steps below, include:
your IconVectors version (see ),
your Windows version,
the steps to reproduce the problem,
the SVG/bitmap file that triggers the issue (if possible),
screenshots of the dialog or error message.
Quick fixes checklist
Try these first; they resolve many “mysterious” issues:
Reset the workspace layout
Show the panels you need (they can be closed/hidden)
Preview Panel: — Ctrl+F8
Layers Panel: — F7
Source Code Viewer: — F3
Center the canvas (useful after zooming/panning or when imported artwork seems “lost”)
— Alt+C
Check for updates
Restart IconVectors after changing language or theme
— F2 → General tab
Workspace and panels
I can’t find the Preview Panel
The Preview Panel is docked by default on the right side of the main window above the Layers panel.
Toggle it from the menu: — Ctrl+F8
If it’s floating, it may be behind other windows—bring it to the front and dock it again.
See also: The Preview Panel.
The Preview Panel looks pixelated or blurry
This usually comes from the Preview Panel render mode:
Pixel mode intentionally displays pixels (and becomes more pixelated when zoomed).
Vector mode displays smooth vector rendering.
In the Preview Panel local toolbar:
Switch Pixel / Vector to the mode you need.
Adjust Scale.
Tip
Use Pixel mode to check crispness at native resolution and small sizes. Use Vector mode to check the general shape and curves at larger sizes.
The Source Code Viewer is not visible
The Source Code Viewer is a dockable panel that can be toggled.
Toggle it: — F3
Note
There is also a “Show Source Code” check item in the File menu in some builds. If you can’t find the panel, use the View menu toggle and/or reset the UI layout.
The interface language or theme did not change
Some UI changes require a restart.
Open — F2
In the General tab, select:
Application Language
Color Theme (System / Light / Dark)
Restart IconVectors.
Tip
If you want IconVectors to follow Windows light/dark mode, choose Use System Setting in Color Theme.
Editing and selection
I can’t select an element by clicking it
Try these fixes:
Select from the Layers panel (useful for very small objects or stacked elements)
Toggle the panel: — F7
Change the selection method
Open — F2
Go to the Icon Editor tab
In Element selection by, choose:
Wireframe (outline proximity) — easier for thin strokes/outlines
Visible pixels (fill and/or stroke) — selects what you actually see
Tip
If multiple objects overlap, use the Layers panel to pick the exact element, then temporarily hide other layers/elements from the layer list if needed.
Elements “jump” when I move them
This is usually caused by Snap to Grid.
Toggle snapping: — Shift+Ctrl+R
Toggle grid visibility: — G
Note
Even if the grid is hidden, snap-to-grid can still be enabled.
The grid is hard to see
Make sure the grid is enabled:
— G
If the grid is behind the artwork, change the grid drawing mode:
— F2 → Icon Editor tab
Toggle Show Grid In Back
My icon looks blurry (not pixel-perfect)
For pixel-perfect icons, make sure you are evaluating the icon correctly:
Use the Preview Panel in Pixel mode.
Toggle the panel: — Ctrl+F8
In the Preview Panel toolbar, switch Pixel / Vector to Pixel
Enable Grid and Snap to Grid while drawing:
— G
— Shift+Ctrl+R
Prefer simple, aligned geometry (avoid accidental fractional coordinates when you need crisp edges).
Tip
When you need to “nudge” geometry precisely, use the arrow keys. (See the Selection Tool topic for pixel-step nudging.)
Tooltips are distracting or cover the artwork
Disable helper overlays:
Open — F2
Go to the Icon Editor tab
Disable:
Show Mouse Tooltip
Show Drawing Help Tooltip
Keyboard shortcuts don’t seem to work
Common causes:
The focus is not in the editor canvas (click inside the canvas first).
A modal dialog is open (close the dialog).
Some toggles are single-key (for example G) and may not work while editing text fields.
As a quick test, try these common shortcuts:
Undo: Ctrl+Z
Save: Ctrl+S
Toggle grid: G
Toggle Preview Panel: Ctrl+F8
Documents, saving and recovery
I can’t save a file (or Save does nothing)
Try these checks:
Use Save As to write to a new location:
— Shift+Ctrl+S
Make sure the destination folder is writable (avoid protected system folders).
If the SVG file is read-only, save under a different name.
Tip
If you are working on template/master SVG files, it is often safer to use Save As and keep the original unchanged.
Can I recover work after a crash?
IconVectors can write recovery information automatically.
Configure recovery:
— F2 → General tab
Set Automatically Save Recovery Every (seconds)
After a crash, restart IconVectors.
Note
Auto-recovery is designed for crash recovery. It does not replace saving your work regularly. Use (Ctrl+S) often.
Importing and opening files
An SVG file won’t open or crashes IconVectors
Although SVG compatibility is broad, some files created by other tools can contain constructs that are difficult to import (complex filters, heavy masks/clips, unusual metadata, etc.).
Try the following workflow:
Update IconVectors:
Try opening in a new window (isolates document state):
— Ctrl+Alt+O
Re-save the SVG from the source tool using a simpler SVG profile (examples: “Plain SVG”, “Optimize”, “Convert text to paths”, “Outline strokes”).
If the SVG is huge/complex, simplify it in IconVectors after import:
Select paths →
Tip
If a file repeatedly crashes IconVectors, include it when you report the bug. IconVectors 1.10 improved SVG compatibility and stability, but edge cases can still exist.
Save As cannot use the destination folder
Save As does not create missing parent folders automatically. Create the folder first, or choose an existing folder and retry. A path component may instead be a file, or access may be denied; those require a valid path or appropriate folder permissions, not merely another attempt to create the folder.
IconVectors 2.10 reports the affected path and captures the native OS error when saving fails. MCP gets the same cause without a modal prompt. A folder can change or become unavailable during saving, so an earlier existence check is not a guarantee. Save failure does not change the document’s path, modified/Undo state or an existing target.
A batch plan reports errors or writes fewer files than selected
First distinguish planning from applying. Planning writes no SVGs or output files. Preview counts describe reviewed candidates, not completed writes. A transport-level MCP success also does not prove the batch applied: inspect the returned operation status and diagnostics.
In IconVectors 2.10, copy/export planning collects independent
file-specific errors rather than stopping at the first one. Read each path,
phase and cause. A legacy error code containing render_failed can accompany
a more precise transform/validation diagnostic; do not assume every such error
is a rasterizer failure. A global safety problem or cancellation can still
leave inputs unreviewed. Fix the reported problems and plan again.
Copy/export plans cannot apply a partially valid set. Original-file batches keep their existing policy of applying only reviewed Changed items; Unchanged, Unsupported and Failed items are not rewritten. A zero-change original plan is not an error, and its Back button remains available. An unchanged SVG copied to another destination still counts as a file write.
If apply fails, do not reuse the consumed plan or blindly retry after a timeout.
Inspect the reported surviving outputs, unrecovered targets and recovery
material first. A missing or externally changed target is not automatically
a successfully written output. If this is detected during post-commit cleanup,
the batch fails even though its journal/backups may already have been removed.
The MCP failed_with_recovery status does not by itself guarantee a backup;
recovery_folder can be empty. Check the explicit recovery paths and
diagnostics rather than assuming automatic restoration is possible.
See Reading batch results and warnings and
Reading batch diagnostics and committed-write counts.
IconVectors omits a redundant generic error when a precise diagnostic already explains the terminal failure. Different errors and warnings are retained, including service and recovery failures. An error list may therefore be shorter without hiding a failure.
Another batch makes a pending MCP plan stale
Earlier versions can reject a pending plan because another batch refreshed the
Explorer folder, even when that plan’s own files did not change. In the
current 2.10 implementation, plans created with explicit paths can survive
unrelated completed work and same-folder refreshes when their frozen dependency
context still matches. GUI previews and use_explorer_selection:true plans
retain their existing strict Explorer generation/revision checks.
Use different batch tools for independent pending plans, keep their returned IDs and review all destinations. Each tool retains only its latest plan; planning again with that tool replaces its earlier one. An attempted matching service apply consumes its plan, and application restart discards all plans.
This is not permission to reuse genuinely stale input. Base files must remain indexed in the same accepted Explorer folder session. Navigation away and back, replaced or edited sources, changed overlays/destinations or relevant Editor conflicts still require a new plan. A replacement file with identical content is not the same observed file identity. If indexing is busy, wait for it to settle; a busy response alone does not prove an old token was consumed. See Keeping independent batch plans usable for the exact boundary.
In IconVectors 2.10, rejection can name the changed/missing/unreadable reviewed input when this can be proved. A metadata or identity conflict is not necessarily a content edit; when only context change is known, that honest context error remains. Correct the cause and create a new reviewed plan rather than retrying a consumed token. More precise errors do not bypass any guard.
Old paint values remain after changing a batch color
An older batch output can contain the original paint value followed by a newer inline override. The SVG may render correctly because the override wins, but its source is harder to read. In IconVectors 2.10, Replace Colors and Convert to currentColor update the controlling local value and remove safely superseded local values of the same changed property.
Do not expect every old color in the file to disappear. Inherited/shared paints
need a local override so other elements keep their appearance. Gradients,
resources, untargeted properties and authored color are not global cleanup
targets. A no-op also retains its original bytes, including pre-existing
redundant values. Do not remove parent/shared declarations indiscriminately:
that can alter unrelated elements or transparency. See
How color batches edit SVG source for the precise boundary.
Batch processing rejects an SVG encoding declaration
An SVG can open in the Editor or export as a bitmap but be rejected by a batch operation that preserves its source structure. These operations validate the original bytes as well as the XML declaration before making targeted edits.
In IconVectors 2.10, an ISO-8859-1 declaration is accepted
when the entire file contains only ASCII bytes, regardless of the declaration’s
encoding-name capitalization. You do not need to change that declaration by
hand. UTF-8 and US-ASCII inputs remain supported.
This exception does not add general ISO-8859-1 or Windows-1252 conversion.
If the file contains actual non-ASCII legacy bytes, use an editor or the source
application to convert the file contents to UTF-8 and write a matching
encoding="UTF-8" declaration. Keep a backup and check accented text,
comments and metadata after conversion. Changing the declaration alone does
not convert the bytes and can corrupt text.
A UTF-8 byte-order mark (BOM) combined with a legacy declaration is conflicting input, not an ASCII-only legacy file. Correct the encoding and declaration together. Unknown encodings and malformed UTF-8 remain rejected. The encoding exception does not bypass XML safety checks or the individual operation’s supported-SVG limits; review any remaining per-file diagnostic.
IconVectors 2.10 validates UTF-8 bytes even when no encoding declaration is present. Invalid sequences identify their zero-based starting byte offset and source path, instead of being described as unsupported paint. Outline Strokes/Auto Gradient classify this as a parse failure; other families retain their existing diagnostic categories. Malformed XML, including illegal XML characters in otherwise valid UTF-8, has a separate XML diagnosis. The file is not transcoded or repaired automatically. Re-export it in genuine UTF-8 and check comments/metadata too; relabelling legacy bytes is not conversion.
Replace Colors accepts valid UTF-8 BOM files and preserves the BOM. The output is still validated before writing; this does not widen the operation’s supported SVG subset or permit malformed XML.
See The Icon Explorer for the batch preview and protected-write workflow.
The standard inert SVG 1.1 DOCTYPE is accepted without downloading its DTD.
Its presence in an output depends on the operation: source-range edits retain
the surrounding source, whereas Editor-model transformations and newly composed
overlays can serialize new SVG without that declaration. Bitmap export ignores
it in a private rendering copy and leaves the original SVG untouched. A missing
output declaration is not, by itself, a lost gradient or failed transformation.
Custom entities and other unsafe declarations remain blocked.
Add Badge Overlays rejects duplicate SVG IDs
An SVG ID should identify one element. Some files reuse a name such as b
on several paths. A renderer may still draw the icon, but combining it with an
overlay can make links or paint references point to the wrong element.
In IconVectors 2.10, Add Badge Overlays handles a narrow safe
case automatically: repeated IDs on ordinary paths, shapes or groups outside
definitions and metadata, with no references to that name. It keeps the first
occurrence and renames later occurrences in a private working copy. The repair
is reported in preview and by MCP as overlay_duplicate_id_repaired with
the input path. Both source files remain byte-for-byte unchanged. The same
repaired content is used for placement, preview and optional badge cutout.
Repaired base IDs remain traceable:
the first b remains b, later occurrences use b-2, b-3 and so on,
skipping authored/allocated collisions. Badge namespacing stays separate.
Inspect the exact repair mapping and query fresh ordinals if editing the output;
do not assume all IDs beginning b- belong to the original duplicate set.
Previously generated output files are not modified automatically.
The batch still stops if the repeated ID belongs to a definition/resource, is referenced by a link, paint URL or accessibility attribute, or if metadata or custom attributes prevent it from proving that renaming is safe. In those cases, keep a backup and correct the IDs and their intended references in the source application before trying again. Do not remove references or blindly replace every matching ID just to bypass the check.
This exception is limited to Add badge overlays. It does not relax other batch validation. The separate MCP duplicate-ID targeting check does not repair the open Editor document. No source files are changed during preview or Cancel.
The SVG opens, but looks wrong
Typical fixes depend on the issue:
Strokes look different than expected
Convert strokes to filled shapes:
— Ctrl+J
Shapes can’t be edited with nodes
Convert to path:
— Ctrl+B
Transforms/scale feel odd
Select the element/group and use:
— Ctrl+E
— Ctrl+M
Placed SVG artwork is off-canvas or scaled unexpectedly
When you place SVG files:
A group is created for each file.
The artwork is automatically scaled to the current document size.
If it seems “missing”:
Center the canvas:
— Alt+C
Select the placed group in the Layers panel and center it:
Center horizontally: — Ctrl+Alt+X
Center vertically: — Shift+Alt+X
Center both: — Alt+X
Center relative to the largest selected element: — Ctrl+Alt+C
If the document size is not what you expect, resize it first, then place again:
— Ctrl+Y
— Shift+Ctrl+Y
— Alt+Ctrl+Y
See also: Place Files.
Drag & drop import doesn’t work
First, verify the file type:
SVG drag & drop performs Place Files.
Bitmap drag & drop performs Place & Trace Bitmap.
If drag & drop does nothing:
Make sure you are dropping the files onto the editor workspace/canvas.
If IconVectors is running as Administrator, Windows may block drag & drop from a normal File Explorer window. Try running IconVectors normally (not elevated) or launch File Explorer with the same elevation level.
Bitmap tracing
Tracing produces messy or unpredictable results
The Trace Bitmap feature is designed for monochrome images (black/white, single color).
To improve the result:
Use a high-resolution source image.
Use clean, high-contrast artwork (remove noise if needed).
Avoid multi-color images.
After tracing, you can often reduce point count with:
See also: Place & Trace Bitmap.
The trace result has too many points
This is normal when tracing high-resolution images with lots of pixel noise.
Run on the traced path.
Use a cleaner bitmap input (solid shapes, no dithering/noise).
Paths and shape operations
I can’t edit a shape with the Path Edition Tool
The Path Edition Tool only edits path elements.
Convert the element first:
— Ctrl+B
Boolean operations produce unexpected results
If Union/Substract/Intersect/Exclude gives an odd result, try:
Convert involved shapes to paths:
— Ctrl+B
Make sure the shapes actually overlap.
Check stacking order (especially for subtraction-like operations):
Bring to top: — Ctrl+Home
Send to bottom: — Ctrl+End
If your shape should have “holes”, consider compound paths:
— Ctrl+Q
— Shift+Ctrl+Q
Note
Many boolean issues come from self-intersecting paths or extremely complex geometry. Simplifying paths can help.
Exporting and developer output
Bitmap export is the wrong size (or looks blurry)
Remember:
Export size is based on the icon/canvas size, not on zoom level.
The Preview Panel Scale is only display scaling.
To control the actual output size:
Resize icon: — Ctrl+Y
Resize canvas: — Shift+Ctrl+Y
Fit icon to canvas: — Alt+Ctrl+Y
Then export:
— Ctrl+F3
— Shift+Ctrl+F3
Exported bitmap has an unexpected background
The checkerboard background is only a transparency indicator.
The Preview Panel light/dark background is only for preview.
For transparent export, use a format that supports alpha (such as PNG).
You can also verify transparency by toggling:
— F2 → Icon Editor tab → Draw Transparency As Checkerboard
Minified SVG looks distorted
If minified SVG output looks slightly “off”, the numeric precision may be too low.
Increase the Minified Code / Decimals setting:
— F2
SVG Code tab → Minified Code → Decimals
You can also increase Decimals for standard (non-minified) SVG.
The Source Code Viewer doesn’t update
Make sure the panel is enabled: — F3
If it was hidden/undocked, reset the UI:
Tip
If you need compact code for embedding, use:
Copy Minified: — Shift+Ctrl+C
Export Minified: — Shift+Ctrl+M
MCP and AI integration
My MCP client cannot connect to IconVectors
Check the local two-process setup first:
IconVectors.exemust already be running on Windows.The MCP client must launch
IconVectorsMcp.exeover stdio with the same port used by the editor bridge.If you changed
Options/McpPort, update the client configuration too.Use the absolute installed path to
IconVectorsMcp.exeand the exact JSON, TOML, or CLI syntax documented for the client.
See MCP Integration and Client setup guides.
The MCP server starts, but tools fail or return unexpected errors
Typical causes:
The editor was not started before the MCP server.
The client is pointing to the wrong port.
The executable path is correct, but the install folder is incomplete.
You are trying to use a hosted web/API connector against a local-only stdio server.
Useful checks:
Call
app_pingfirst.Then call
app_getInfo,app_getCapabilities, andapp_get_workspaceto confirm the application and workspace.Inspect
document_getInfoandselection_getin Editor, orexplorer_get_statein Explorer, before mutation.If several IconVectors instances are open, confirm which one owns the configured port. There is no instance selector.
For Claude Desktop, verify that the current
Axialis-IconVectors-Claude.mcpbis installed and enabled; restart only when troubleshooting requires it.Distinguish the client’s startup/request timeout from the sidecar’s 10-second application-bridge I/O timeout.
See also MCP Integration.
MCP reports an ambiguous element ID
In IconVectors 2.10, the ambiguous_element_id error means
that an ID such as b identifies more than one element in the current SVG.
The MCP connection can be healthy while this individual request is rejected.
IconVectors no longer guesses the first element for a singular ID lookup or
ID-targeted element operation, and the rejected request does not apply a
partial edit.
Ask the assistant to run dom_query with
{"query":{"id":"b","limit":1000}}, inspect the returned elements, then
use the fresh ordinal of the intended element. If all matches should change,
choose all intended current ordinals through a tool that supports multiple
targets. Do not blindly retry the same ambiguous ID or use only the first
candidate. Check the result limit before assuming the query found every match.
The error reports the requested ID, exact match count and up to 32 candidate ordinals, with an indication when candidates were truncated. These are current document references, not permanent identifiers: query again after changing structure. Unique IDs and explicit ordinal references still work. No IDs or resource links are automatically rewritten in the Editor.
See Duplicate element IDs and safe targeting. The narrowly bounded duplicate-ID repair in Add badge overlays is a separate copy-only workflow.
The 2.10 companion exposes the error details in both its text result and
structuredContent, so clients that display only text can still show the
candidate ordinals. If these are missing, check that the companion matches
your 2.10 application.
For shared multi-target editing use
{"target":{"elements":[{"ordinal":4},{"ordinal":9}]}}, not
target.ordinals. The separate selection_set tool still uses top-level
ordinals. See Error details and multi-element targets.
MCP opacity queries do not match
dom_query compares stored attribute strings when using
query.attribute.equals. It does not compare numeric values or computed
appearance. The existing import sanitizer can store opacity="0.500000";
the query string "0.5" will not match that text. Inspect the element with
dom_getElement and use the exact returned spelling. The transparency may
instead come from an inline style, a fill/stroke opacity or a parent, so do not
assume every half-transparent element has its own opacity attribute.
Generated-gradient cleanup does not change this comparison behavior or Make Disabled Version’s existing behavior. Do not rewrite unrelated attributes just to make a string query match. See Attribute queries compare stored text.
Performance
The editor feels slow or less responsive
If the UI feels heavy, try reducing on-screen helpers (especially on very complex icons):
Hide the Preview Panel if you don’t need it constantly:
— Ctrl+F8
Disable helper tooltips:
— F2 → Icon Editor tab
Disable Show Mouse Tooltip and Show Drawing Help Tooltip
If the checkerboard makes the display busy, disable it:
— F2 → Icon Editor tab
Disable Draw Transparency As Checkerboard
Ensure you are on the latest version:
Updates, activation and internet
Update check or activation fails behind a proxy
If your network requires an authenticated proxy:
Open — F2
Go to the Internet tab
Enable Use Proxy with Authentication
Enter Username and Password
Then try again:
Auto-update is not desired in controlled environments
Disable automatic update checks:
— F2 → Updates tab
Toggle Automatically Update Axialis IconVectors
You can still run updates manually with .
Update subscription reminder is visible in the toolbar
IconVectors can show a toolbar reminder when your update subscription is within 30 days of ending, or when the subscription period has already expired. To hide only this toolbar reminder:
— F2 → Updates tab
Disable Show a toolbar reminder 30 days before the update subscription ends
The renewal command remains available from the Help menu and from the account menu when renewal is relevant.
Getting support
How to report a bug effectively
Use:
Include the following:
IconVectors version ()
Windows version
Exact steps to reproduce
The SVG/bitmap file (if possible)
Whether it happens with all documents or only a specific file
Screenshots (and, if relevant, a short screen recording)
Tip
If the issue relates to selection, include your current selection mode setting: → Icon Editor tab → Element selection by.