General guidelines to avoid UUID problems

I would like guidelines spelling out how to avoid problems with UUIDs.

I have had many problems with UUIDs. Symptoms include elements of the Library Editor not showing up after a save that seemingly works without error. Also problems with updating the libraries used by the schematic saying UUIDs are referenced that don’t exist.

These problems often manifest asynchronously with the symptoms. It’s really hard or impossible to relay how the problem occurs when this is how you find them.

It’s also hard to figure out the name used by an element by UUID, so figuring the problem out is a total quagmire. A couple hours with Claude (AI) did not solve the problem either. It concluded my data is present but the application won’t show it.

From a user’s perspective UUIDs are a house of cards.

I have made three PCBs so far and each worked on the first pass. I’m thrilled, but the pain of using the app is really high.

Hello davei,

i don’t fully understand which kind of problems you see. Maybe you want to send more detailed information like “i did this and then faced that…”
And probably the developers are able to give much more info.

First question : Why are you even worrying about UUIDs? As i understand it, these are just an internal means of organizing library elements. And libre pcb does a very good job taking care of them. Even though I myself have many custom devices in the lib i never hat to care about UUIDs.

Only thing i could imagine is that you copied library elements yourself on file system level, which you normally shouldn’t do.

Did you read Create Library Elements | LibrePCB Documentation
and
Library Conventions | LibrePCB Documentation ?
I think that there are already some do’s and don’ts.

From my users perspective libre pcb is far from being a pain to use.

Sasmus,

Thank you for responding, it’s very kind of you.

This is my 4th PCB design with the prior 3 being complete successes.

I’m using LibrePCB to build all six forms of Library Editor elements, the schematic, and board layout. I do a little importing of Eagle files and also read in 3-D step files. These two things bring in data not originating in LibrePCB.

I would never involve myself with UUIDs, but things in LibrePCB have bugs. These present themselves as, for instance, complaints about UUIDs during library updates.

I would not copy file system elements outside the tool unless I found no choice. After I found no way to fix the problem or learn the elements containing the UUID(s) of the problem I would search/grep the files outside the program. After hours of no success fixing the problem(s) I went to Claude for suggestions. After hours with Claude it started suggesting I copy files outside the tool, which I did because I could see no choice. I believe only two copies of files were done and these did not fix the problems. Claude saw the files as containing UUIDs that were referenced but not present before the copies. This certainly could make things worse, though I saw no difference.

Again, these problems present symptoms asynchronously with the offending action by the user. If they were synchronous, I would happily tell you exactly what I did. Instead, I just want guidelines to avoid bugs. It’s pretty serious when LibrePCB is crashing repeatedly, losing data, and leaving lock files everywhere. I’m not seeing one bug but at least two involving UUIDs and, no, I don’t know the sequence of events. A substantial amount of activity passed before I ran into: repeated crashes, inability to save elements in the Library Editor, and errors during the “Update Project Library” command.

I think LibrePCB fairly easy to use, but it does have bugs, and these bugs related to UUIDs are particularly nasty since the user is crippled from the start without a map of UUID to element. For instance, when the library updates fail with a UUID problem the error states the UUID in question. It does not state the element the UUID was associated with nor what to do about the problem. Another example is when the Library Editor acts like it saved a new element, but the element does not appear in a list (say for instance, as a package). Then one loses the work done since saving does not work. Upon repeating the work, one loses it again, because what is causing the problem is unknown. The user, me, does not know what steps are needed to avoid the problem.

In my case, I think the problems are related to copy and paste operations and pads - just a guess. Perhaps pasting or creating duplicates in some manner leaves two things using the same UUID which would create havoc later. Again, I work within the program, not the file system, unless bugs force me to do otherwise.

I believe I have already read LibrePCB documentation on library elements, but will peruse it again.

I am asking questions because I like using the tool. As a long time developer, I see it as marvelous. All programs have bugs. How they are handled matters.

I’m sure others have or will run into these problems. My hope is enough have seen the problems that guidelines to avoid them exist.

Thank you for the links. I apologize I cannot supply a sequence of commands creating bugs. That is why I only asked for guidelines.

I agree to both of you – actually you shouldn’t need to care about UUIDs and those kinds of errors should never occur if you don’t do nasty things. But I also agree it shouldn’t hurt to have some documentation / guidelines about our UUID concept. So I gave it a try:

It may not be perfect & complete, but I hope it already helps to understand the system.

In any way, it’s important to highlight that those kind of errors are not bugs. It is expected behavior to get some “…no element of type X with UUID Y…” error if there is an invalid reference in the libraries. Nothing is going wrong except that someone has broken a library element. It’s not LibrePCB’s fault if a library element was broken, LibrePCB just detects and reports this fault.

Also note that in LibrePCB 2.1 I have made a big improvement to avoid these issues from happening. Older LibrePCB versions already notified the user if he made breaking changes in library elements, but many users have just ignored the message and then created bug reports, complaining about broken libraries etc. So I have changed the warning in a way that cannot be ignored anymore, the user now has to take explicit action, and making breaking changes is now much harder.

This doesn’t sound like it is related to UUIDs in any way. LibrePCB is really crashing? That would be a serious bug and I hope you report the steps how to trigger the crash. But in any way, this will never cause problems with UUIDs. File access is implemented in a very very safe way in LibrePCB, and a crash shall never end up in some invalid state – except from losing unsaved changes, which is obvious.

Urbruhin,

Thank you! I will give these a read.

FYI: I’m on a Mac using LibrePCB:
Git revision: 18a3d4589
Build date: 2024-04-03 14:43:25 (PDT)

I understand what you mean about “those kind of errors are not bugs”. It’s totally fair to assert that when there are valid ways to operate that cause invalid UUID references. When I get a message from Update Project Libraries with such a warning, I want it resolved. If I cannot resolve it my list of warnings will grow and I’ll start inadvertently ignoring them. I’ve seen this my whole career as a developer (I have written similar tools for ICs which gives me a special talent for breaking them :wink: )

But… I’m seeing bugs - many crashes - before I resorted to file system changes (which didn’t work). I am near certain the problem involves UUIDs, missing, extra, or three-eyed - I don’t know. I also suspect pads are involved. I will do my best to corral the sequence, but as I have noted the problem is quite asynchronous. Perhaps one Library Editor element type change is badly interacting with another, but one doesn’t see it right away.

Please don’t think for a moment I am disappointed with the program in general. I am very happy. Thank you. Developers for the program have good reason to be proud. Getting through the problems is all I’m hoping for.

@davei - thank you for the additional information.

This one will probably be somewhat more difficult, i think.
Though i‘m a LibrePCB user since Version 1 i swear i never had such problems or even a single crash.

Only things i never did is eagle imports and copy on file system level. (I also use *.step imports regularly, so i guess that this has nothing to do with it)

Would be very helpful if you manage to isolate the steps involved to trigger those.

Oh that’s a very old version. It also still has the “problem” that it doesn’t prevent you from doing breaking changes. I’d strongly recommend to update to the latest LibrePCB version.

I agree it would be desired if LibrePCB helped to resolve those issues. At the moment it only reports them. Some day the project library updater will be improved to emit more details about the issues, and ideally providing options to resolve them. But anyway, the actual issue (a breaking change) already happened way before the update, the error during the update is only a symptom of it. So usually, at this point in time it is already too late to fix the issue.

Here again I’d recommend to use the latest LibrePCB version. Any time spent on investigating issues with older versions is wasted time. Even if there were bugs in the older versions, they might not exist anymore with the latest release.

Okay, I downloaded and installed 2.1.0.

There’s no legend to the icons used, so I no longer know what type of element I’m working on. Remember, these are abstractions and names not entirely consistent across tools.

I am now unable to make a simple update to a device and reflect the change in my board layout unless I build a new version in my library. I don’t want my library cluttered with parts created in the iterative process of building a library where I am the only one to use it and am using it for the first time. To me that is very broken.

I have taken these steps:

  1. Made the change to the board layout of a library element, say, a capacitor.

  2. saved it

  3. found the element into which the association of the layout and symbol is made and tried to update that. It refused. I finally found how to unlock it. Because I cannot measure in that interfaces layout window (ruler won’t leave the grid), I don’t know if that update worked

  4. went into Project Library manager and did an update:
    successful stuff…then
    [ERROR] No symbol with the UUID “e5bccd32-e2e9-4773-a6c1-45605c3921b7” found in the project’s library.
    [ERROR] Failed to update library elements! Probably there were breaking changes in some library elements.

  5. Did a Rescan Libraries

  6. Opened the board and removed ALL the elements of the device type I want to update.

  7. Re-placed, in the layout, each of the above. The new placements do not reflect the change.

    I have done various incantations of the above to no avail. My conclusion is, sadly, I cannot use the tool with the update process as it is. I have a lot of work invested (around a hundred library elements) and am very disappointed. I was able to get boards done under version 1.1.0 (with update problems but I got through them), but now it appears I cannot without polluting my library with every incorrect iteration I make as I develop the library.

It’s sad to hear that. But to be honest, I can’t confirm those issues.

My guess is that you made a lot of breaking changes in the past, leading in a hell of a mess, and now you have to deal with the resulting problems. Honestly that confirms that it was necessary to make it harder to make breaking changes (the new “unlock” system). Though nobody else has ever reported so many problems. Usually, users ignored the breaking changes warning once, run into a problem, and learned from it not to do it again.

I don’t understand what you mean, can you please elaborate?

That is not true. LibrePCB does not prevent you from updating a device. Even if the change is breaking, you can do it after unlocking – a matter of a mouse click. (If this should be done, is a different topic – but it is possible)

LibrePCB does allow creating library elements in an iterative process. But you should do the important parts of a library element once, and not change it afterwards. I mean, don’t create a package with 7 pads, then add in to a board, and then add one more pad to the package. This doesn’t make sense. It should be easy to do the number of pads first time right. Anything else like silkscreen, documentation polygons, pad sizes, courtyard etc. can be added/modified later in an iterative manner. Same for devices – pick the correct component & package at the beginning, this shouldn’t be hard. MPNs, datasheet etc. can be added later.

Did you read and understand the UUID guidelines I have written? Was this a valid case for unlocking? It sounds like you just fundamentally worked against the guideline (adding a library element to a project, and then unlock it – this will end up in troubles for 100%).

You removed or replaced a gate of a component after it has been added to the schematic. A breaking change after using the component in a project → troubles.

I should add one more recommendation to the guidelines I have written: Do library elements right from the beginning on. Do not just quick&dirty create some packages, components and devices, adding them at a very early stage to a project, and then iterate 20 times over them to make them right. Maybe you got into the current situation due to this approach. This approach works not well with LibrePCB – and honestly, it is wasted time to iterate so many times. Just do library elements right at the beginning. Smaller errors like silkscreen, courtyard, pad sizes, MPNs, datasheets can be fixed later, that’s not a problem. But the fundamental things of library elements need to be done right.

By the way: My comment above is a recommendation for an average LibrePCB user. As soon as you fully understand the UUID system, you can take advantage of this knowledge and start to work more iterative. I do breaking changes on library elements from time to time and never run into troubles. If you know how to do it, it works perfectly fine. But it’s clearly not a recommendation for beginners. If you don’t understand the system (yet), don’t make breaking changes.

The concept of LibrePCB 2.1.0 is not different from 1.1.0 at all. Everything you could do with 1.1.0 you can still to with 2.1.0. It’s exactly the same. The only subtle difference it that breaking changes now need an explicit user confirmation (unlock) while in 1.1.0 it was just a warning which didn’t need a confirmation. It’s just a small UI thing. The banner even already existed in 1.1.0, it was just yellow instead of red and didn’t contain an unlock button. Under the hood, 1.1.0 and 2.1.0 work exactly the same way and provide the same functionality regarding library management.

Nope. I could at least get my change to a library element’s silk screen to appear in a board layout.. Now I cannot. I gave you the sequence of events I used. Some of those steps may not even be needed, but in desperation I tried to put together the most likely way to assure changes would be seen at the board. Instead of commenting what step I was doing was right, wrong, unnecessary or missing, I got something else, blame.

I guess adopting the verbiage “breaking changes” gives a wide license to make things difficult where they needn’t be. I think that’s a way to discard what I say and I’m faced with very real problems with the tool.

There are six different elements used in LibrePCB 1.1.0. They were in clear categories with names and icons. The abstractions they were meant to allow were not so obvious, but that’s a necessary step in learning. What’s not necessary is to open a window on one of these elements and not clearly know which of the six you’re looking at. Yes, its easy for one has used the tool a long time but an unnecessary impediment. Really, this is a small problem and easily fixed compared to updates not being possible to view in LibrePCB 2.1.0. It just makes it easier for people to learn.

Please read the steps I took and explain why I cannot see the updates. That’s a deal killer no matter how much I like the program.

I read and understand the purpose of a UUID. I knew the purpose before I read it. If I never saw a problem where I needed to associate a UUID with a named element, it wouldn’t be a problem. Your Update Project Library process outputs UUIDs, especially important when it identifies a problem with them. Why output them if a user never is to need them - though I’m proof that a user does need them and then, rather than the program giving the user a hint of what the UUID was associated with, I’m forced into a file system dive. You cannot have it both ways “UUIDs a user should never have to deal with” and “here’s an error identified by UUID”. Furthermore, when an error with a UUID is output the process does not tell you what was successful and what part of the process did not complete - at least in a meaningful way to a user who should never see UUIDs.

First, I cannot view a silk screen update to a library in the board layout. That was true before and after I tried the “Unlock” button, which I did when nothing else worked. I did not ignore what you said and wrote, it just didn’t work. Second, I’ll just have to become perfect, but it might be a while. When the DRCs for a PCB vendor changes slightly I will perfectly ignore them. When I learn a better way to abstract the device I won’t seek a way to facilitate the change with ease. Please see this as a ask for improvement.

Do you believe everyone facing these problems tells this readership? I know it’s easy to put someone off saying no one else has the problems, but you really don’t know that.

That’s neither related to LibrePCB 2.1.0 nor to your silkscreen change. Due to a breaking change in a component, the project library cannot be updated. LibrePCB 1.1.0 would not behave differently. Believe me – it would have failed too. The project library updater of 1.1.0 and 2.1.0 are identical.

Hmm actually I pointed here what was the wrong step:

So to make it clear again: The unlock was the wrong step.

I agree there is room for a lot of improvements regarding the project library updater. It would be better to handle breaking changes in a nice way instead of failing/rejecting the update. But that is a ton of work and I had no time yet to do this. However, I have always been honest about this situation, as explained very clearly in the application:

There is also clearly written why your silkscreen change was not the reason for the failed update. If any library element fails to update (a component in your case), none of the library elements will be updated.

If you don’t accept this “unfinished” situation, I’m really sorry. I implemented this updater to provide a useful feature, even though it is not perfect yet. Due to my limited resources, the only alternative would be to remove this feature. Then you will never have problems with breaking changes. But you also wouldn’t be able to update library elements in a project.

The “unfinished” state is also the reason for the error messages which contain UUIDs and are not very useful for an average user. I am aware of this. Those are low-level messages, not intended for displaying to end users. We still display them because it’s better than showing no error at all. You have to accept that it will take time until we can provide a more powerful & user friendly updater. LibrePCB is run with very limited financial resources. I’m not a magician, I cannot build an enterprise software like Altium with a few 100$ per month.

That’s still the case in LibrePCB 2.1.0:

If you mean another part of the software, please post a screenshot.

Again: The problem is not the silkscreen change. It was a breaking change in a component. But unlocking a package will lead to a new update error in future. Before, it was only a problem in a component. After unlocking the package too, you will have a problem with the component and the package. Also, changing silkscreen doesn’t require to unlock since it is not a breaking change. You have made more changes in the package which you didn’t tell me. Otherwise the unlock button would never have shown up.

Anyway, this discussion does not help us at all. You have to fix the mess of a hell in your libraries and projects to make the problems stop. And you have to follow my guidelines to avoid further problems in future. Or, if you are not willing to do so, you have to wait (maybe several years) until the project library updater is able to handle breaking changes.

Since I want users to be happy with LibrePCB, I make you an offer now: If you guarantee me to never unlock library elements again which have already been used, I’d be willing to fix your hell of a mess. However, this would require to send me all your libraries and projects. Only with all libraries & projects available, it will be possible to identify and fix breaking changes. If you like to let me do this, you can send me the files to the email listed at Contact | LibrePCB and I will send you back the fixed files.

But again: Only if you don’t use the unlock button anymore for already used library elements. I’m not willing to invest my time to fix a mess that will happen again in future.