Skip to content
Handbook Version v2026.04.17.1 Released 2026-04-17
Download PDF

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

  • iOS
  • macOS

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

  1. Identify whether the failure happened before file selection, after file selection, or after entering the workspace.
  2. Check which import path was used and whether the source should be supported there.
  3. Compare the observed behavior against the failure patterns below, including unchanged re-imports and partial DSN degradation warnings.
  4. 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

  1. Did the failure happen before file selection, after file selection, or after entering the workspace?
  2. Did the app show a clear error message?
  3. 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 SES as 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