The purpose of the cache library
KiCad version 5 and earlier do not include symbol information in the schematic file format. Without any counter measure changes to the libs would change the schematic without user control (worst case a symbol is deleted from the lib and the project looses its information).
This is where the cache lib comes in. Anytime a user adds a symbol to the project it is copied to the cache lib for save keeping (unless the same symbol is already in the cache). If now the libraries change then there is a way to protect the schematic from change. This means this library should not be changed by the user directly and it must be included when the project is archived, shared or backed up. See Project and libary setup for sharing and collaboration
The purpose of the rescue library
The rescue lib is a possible result of the protection mechanism. If KiCad discovers that a symbol in the cache lib differs from the one in the normal library then the user is presented with an option to rescue it. If the user declines this offer then the cached symbol is overwritten with the current state of the normal lib.
However, should the user decide to rescue then the rescue process copies the cached symbol into the rescue library. The symbol references in the schematic are updated to point to this new instance inside the rescue lib and the rescue lib is added to the project local symbol library table if required.
What is not cached?
The cache library does not contain the symbol documentation nor does it hold the values of fields. These are stored in the schematic file itself as they can be set to different values for different instances of the same symbol. Which also means that not rescuing the symbol will keep the field values as set in the schematic. To update fields from the library use edit->update fields from library.
Changes to graphic elements does not trigger the rescue dialog. There is no way to protect your schematic against such changes other than working with project local libraries. (Only changes to pin positions trigger the rescue dialog as these changes would run the risk of damaging your project)
File names
- For the rescue library: [project name]-rescue.lib
- For the cache library: [project name]-cache.lib
The rescue process
The rescue dialog is used for controlling the rescue process. A symbol is either selected to be rescued or to be updated from the library with it.
If the symbol is no longer found in the library then the library section of the dialog is empty. Rejecting the rescue will result in KiCad showing the symbol as a question mark. A valid reason for the rejection is if one wants to manually reconnect the missing symbol to its correct part in the library. In most cases however accepting the rescue in this case is what you will want.
Known bugs
Changing a multi unit symbol does not trigger the rescue dialog in 5.1.5. See https://gitlab.com/kicad/code/kicad/issues/3879
Why does my project suddenly display some (or all) symbols as question marks?
This happens when KiCad does no longer have symbol information. For example because you did not rescue symbols missing in the libraries (you deselected them in the rescue dialog or clicked cancel).
Another option is that your cache library was lost or damaged.
Fixing this is not straight forward. You will need to find the original library version that was used when the project was created and then need to set up KiCad to that library. This will allow the cache library to be regenerated.
You can alternatively use the edit library references dialog to point the symbols to equivalent symbols in your current library version (This does not check if the symbol you now chose is really equivalent! So double check the result carefully. See remap tutorial linked below for details about that option)
Special case: The project was made in v4 and opened in v5
Another possible reason for ending up with a number of question marks is that you updated from version 4 to version 5 and made a mistake when remapping. See Converting KiCad version 4 projects to version 5 (Remap a project) (includes a detailed description how to fix this problem and how to avoid it in future)