Import Failures¶
Goal¶
Help you quickly decide whether the current failure is an unsupported input, an import-path mismatch, or a proactive runtime protection stop.
Supported Platforms¶
iOSmacOS
Intended Audience¶
- Users whose import path did not behave as expected
- Testers triaging import failures, ignored imports, or degraded import outcomes
Prerequisites¶
- You have a specific import case, message, or reproduction path to inspect
- If possible, keep the source file and the exact import path that triggered the issue
Steps¶
- Identify whether the failure happened before file selection, after file selection, or after entering the workspace.
- Check which import path was used and whether the source should be supported there.
- Compare the observed behavior against the failure patterns below, including unchanged re-imports and partial DSN degradation warnings.
- Record the exact message and source context before retrying.
Result¶
- You can narrow the issue down to unsupported input, path mismatch, protective stop, unchanged re-import, or a local degradation case.
Look at These Three Things First¶
- Did the failure happen before file selection, after file selection, or after entering the workspace?
- Did the app show a clear error message?
- Was the action a new import, append revision, or SES?
Most Common Failure Types Right Now¶
1. Unsupported input type¶
Typical signs:
- the app directly says the extension is unsupported
- the flow stops after you pick the file
Suggested actions:
- first confirm whether you used the design or manufacturing path
- then confirm whether the input belongs to the currently supported set
2. Wrong IPC-2581 import intent¶
Typical signs:
- the file can be selected, but the resulting import behavior is not what you expected
Suggested actions:
- import it again
- reselect whether it should be treated as design-side or manufacturing-side data
3. Incorrect SES usage¶
Typical signs:
- trying to import
SESas if it were a normal new document - or the current document has no usable base revision
Suggested actions:
- open the target document menu
- start from
Import SES - select a valid base revision first
4. Large IPC-2581 blocked by preflight¶
The current implementation includes memory preflight protection for very large IPC-2581 XML inputs:
- it estimates peak usage based on file size, physical memory, and platform type
- if the risk is clearly above the safe budget, the app stops before opening
This is intended to avoid OS-level termination caused by memory exhaustion.
5. Another import task is already running¶
Only one PCB import task is allowed at a time in the current implementation. If a previous import has not completed yet, the next import request is rejected with a status message.
6. Same-name, same-format input is judged as unchanged¶
The current implementation compares original source bytes when you re-import a source with the same document name and the same format:
- if the newly imported original source is identical to the current revision, the app reports that the import was ignored because nothing changed
- this is not treated as a failure; it is how duplicate revisions are avoided
- if you expected a new revision, confirm that the file contents really changed
7. DSN local geometry degradation after a successful import¶
Typical signs:
- import ultimately succeeds and the document opens
- but the developer log or console shows warnings such as
skipping display object variant ... no valid contours could be extracted
What it means:
- the importer could not extract a valid contour for a small number of display variants, so those local variants were skipped and the rest of the board continued importing
- this behavior is meant to avoid failing or crashing the whole board import, and it usually affects only local rendering rather than the entire document
Suggested actions:
- first confirm whether the affected area is still usable for the task you care about
- if the missing geometry matters, record the warning text, the original
DSN, and the reproduction steps for follow-up investigation
KiCad-Specific Note¶
Even if a KiCad board imports successfully in 2D terms, missing or unreadable project-local 3D assets may still surface as issues later in 3D or diagnostics. That does not always block 2D opening, but it can reduce 3D completeness.
What to Record¶
- platform and device
- import path type: design / manufacturing / SES
- original file type and size
- the original error text
- whether it reproduces consistently
- whether another import task was already running
Common Questions¶
Why can some manufacturing inputs be imported even though they are folders?¶
Because the manufacturing path accepts directory-style inputs. Whether import succeeds depends on whether the importer can recognize the directory as a supported manufacturing package.
Why is there no new card in the library after a failed import?¶
That usually means the failure happened before document creation, such as unsupported input, preflight rejection, or importer detection failure.
Why didn’t I get a new revision after importing the same file name a second time?¶
If the app says the import was ignored because nothing changed, that means the newly imported original source is identical to the current revision. The current implementation skips it instead of creating a duplicate revision.
It worked on the second try. Should I still record it?¶
Yes. Intermittent failures still matter for stability evaluation.
Last Verified¶
2026-04-17