Like any software, Figma enforces that any document you create is valid. For example, we make sure that there's no way for a user to make "Frame A" the parent of "Frame B" and make "Frame B" the parent of "Frame A" at the same time. After all, what would that even mean?
Inside the tool, we enforce these restrictions by limiting the actions that you can take. Similarly, we make sure that plugins can't create invalid documents by throwing exceptions if an operation is invalid.
A key part of building a quality plugin is to get familiar with these restrictions. This way, your plugin is be robust and won't crash if the user runs it on a document configured differently than your test files.
These restrictions are documented here as well as in the details page of various properties and functions.
Error: in <property/method>: Expected <property> to have type <expected type> but got <actual type> instead
Functions that take arguments and property setters always have restrictions on what kind of values you can give them. For example,
opacity can only be set to a number. It must also be a number between 0 and 1. So if you write:
figma.currentPage.selection.opacity = "test"
the above would throw
Error: in set_opacity: Expected "opacity" to have type number but got string instead.
There are too many variations of this error to list out for every property, but hopefully the error message should be self-explanatory. Please refer to the signature of the methods or properties you're using to know what kind of values are accepted.
Some nodes are read-only. In particular, components and styles that exist in the team library have a local copy that you can access, but it's only a copy. Therefore, attempts to edit them will throw this error.
Not all properties are overridable on instances. For example, you can't change the order of children in an instance, or their position. To check whether a particular property can be overriden on an instance, use the Figma editor and try to override that property.
Many text properties require the font of that text node to be loaded before it can be set. Read more about how to work with text.