Document Version v2026.10.17.0

Import failures¶

Supported platforms and audience¶

Apple-build users; use this page to distinguish source errors, mismatched paths, and open failures.

Keep the original input, extension, entry used, and error text.

Confirm whether you used File or Folder. Folder create requires a valid KiCad project and cannot import an arbitrary manufacturing directory.
Multi-sheet schematics should supply a complete project. A single .kicad_sch does not automatically fill in external child sheets.
Let cloud drive or a file provider download the source locally before you choose the file / directory.
For IPC-2581, choose design or manufacturing intent according to the actual use.
If the app reports no change, check whether you re-imported the same name, format, and byte content. That can be normal deduplication.
Record whether failure happened at file selection, library ingest, or Viewer first-frame preparation. Wait for an in-progress import to finish before trying again.

Symptom	Next step
The file picker cannot select the source	Check the entry, extension, and format coverage
The directory is missing a project file	Provide a complete `.kicad_pro` project, or use File to import a single board
The document already appears in the library, but opening fails	Keep the document and record the Viewer stage and error
2D opens, but 3D assets are missing	Check models and project dependencies; do not classify this as a total import failure
The canvas is missing key geometry	Record the missing range and sample. Opening successfully is not the same as being complete and correct

The problem is located to source, entry, reading, parsing, or display, which makes reproduction easier.

No. Parsing depends on actual content and project structure.

Yes. Record the first failure and any retry difference. Do not let one later success overwrite the original error.

2026-09-11: checked against the current Library Guide, project hands-on, and source rules. Manufactured error inputs were not created one by one.