Custom layout troubleshooting
How do I know the layout is rejected?
It's easy to recognize when a layout is rejected; instead of showing the layout itself, the display either shows only the background image or the background image along with the action icon and name.
What can go wrong?
The three most common errors that lead to a layout being rejected are...
- JSON syntax error. The Stream Deck software is highly sensitive to file syntax; even the slightest syntax error, such as a missing or extra comma, will cause the layout to be rejected.
- Objects extending beyond the 200x100 pixel canvas area.
- Objects overlapping on the same zOrder.
How can I figure out what's wrong?
If there is an issue with the layout, you can check several places to find information about the problem. Depending on the nature of the issue, it may be described in different locations or not mentioned at all.
The first place to look is in the editor. If there is a JSON syntax error, an error message will likely be visible in the editor.
- If you cannot find anything in the editor, the next place to look is the Stream Deck log file (not the plugin log file). For some reason, pure JSON syntax errors do not appear to be logged, but you might find errors like this:
Layout instantiation failed: in layout 'Cubase_Volume_Layout' of plug-in 'se.trevligaspel.midi' element 'l_toptext_full_width' cannot set property 'alignments' to 'center' (string): entity misused or does not exist
RT ERROR: invalid geometry, items out of bbox in layout: Cubase_Volume_Layout
The first one has a misspelled property "alignments" which should have been "alignment" (in singular). The second one has an object that is defined to span outside the 200x100 pixel display area. These errors do not break the JSON syntax and will not be visible in the editor. What is logged by the Stream Deck software may vary between different Stream Deck versions. - The next place to look is to use an online JSON syntax validator to verify the syntax of the JSON file.
- If you cannot find any error information in any of the above places, I recommend minimizing the layout to a single object and then adding objects one by one until the layout is rejected. When you identify the object causing the error, try to determine if the issue lies with the object itself or if it arises from a combination with other objects (by overlapping on the same zOrder).
Properties are not configured according to the layout
If there are specific properties that don't seem to be set according to the layout, please check the Elgato property documentation and verify the data type for the property. Property data can be either a string, a number or a boolean. Strings must be enclosed in apostrophes or quotation marks; numbers and booleans must not be enclosed in apostrophes or quotation marks. Example:
"enabled": "true"
This will not enable the object. It is not a JSON syntax error, so it will not be logged anywhere. Still, the Stream Deck software requires the data to be of the correct type according to their documentation, so for this particular example, the correct definition is:
"enabled": true
Important note!
If you're experiencing layout issues and constantly adjusting it to fix the problem, you may find that even when you know the layout is correct, it still gets rejected. I'm not entirely sure why this happens, but it seems that the Stream Deck software eventually gives up and quits managing the layout, no matter what you do. The only way to "fix" this problem is, as far as I know, to restart the Stream Deck software.