I have started a gist with a guide on how to troubleshoot modules, directed to users that have problems after installation of a module and don’t know what to do / where to look.
I’d like to use it as a reference for troubleshooting threads.
This is still a work in progress and not fully complete.
Any contribution is HIGHLY appreciated.
Find the source here
https://gist.github.com/lavolp3/db7de8c0664ba95e8b9247ba685095fe
This documentation describes the workflow to debug Magic Mirror modules. It is to the most part valid for any Magic Mirror module out there but especially directed to my modules and their debugging function.
1 - HELP!
Well, help is on the way. Let’s get started!
There are two main issues that you’ll face:
1.1 - The mirror won’t show
The two main reasons are:
- config.js is probably not interpretable anymore. Check out debugging config.js
- the DOM (document object model, which is the sum of objects in the HTML document created by the code) could not be created due to syntax errors. Check out debugging main.js
1.2 - My module won’t show / won’t show complete / shows unexpected behaviour
There probably is a syntax error in your module. Check out debugging main.js
1.3 - My module won’t update
You may have a problem at the server side, probably in the node_helper. Check out debugging node_helper
1.4 - My module shows up but looks weired
There are many possible reasons for that but it’s worthwile to have a look at css. Check out debugging css
2 - Bug hunt
This describes the debugging workflow. You can do this workflow from start to finish to check for all obvious issues or check specific parts coming from part 1 above.
2.1 - Activate debug function
This is valid for my modules oand some others, but not nearly all. THe config options for my modules generally include a debug function. Set it to true to receive much more debugging output.
debug: true
2.2 - Debugging node_helper
The server side of the mirror works in the background, usually you can’t directly see the errors the modules create here.
2.2.1 - pm2 logs
If you have pm2 installed it is possible to check for errors in a running system using the command
pm2 logs
You can add the flag --lines xx to include more lines.
pm2 will throw out a tail of the last logs in three different categories: pm2 system logs, error logs, and info logs. You’re especally interested in the error logs (usually red), so have a look there for anything related to your module.
2.2.2 - npm dev mode
A more general way is to use the included npm dev mode.
pm2 stop all
npm start dev
It is important to stop all instances of the mirror before starting here, otherwise the dev mode won’t work because the port (usually 8080) is blocked by the other instance.
Above command will throw out all messages from the server side that are sent to the console and that you usually wouldn’t see.
Here you can have a look if your module creates an error.
If you want to post an issue to the forum or to github, it’s best to attach an output of this.
You can stop the dev mode with ctrl+c.
Then start pm2 again using the command pm2 restart mm or however the alias of your MM instance ins named.
2.3 - Debugging main.js
2.3.1 - Using the browser to debug front-end
To debug the front-end side (anything that is in your main.js) you can use your browser on the laptop or computer. It is advised to use Chrome or Firefox.
Open your browser and type into the address field
http://magicmirror:8080
Here you obviously need to use another host name (instead of magicmirror) if you have changed it. You will know whether you have. The general host name is magicmirror. You may have also changed the port in config.js. Use the one you chose.
If you have a running system (via pm2, or one of the node commands node serveronly, npm start dev etc), your browser will build up the mirror frontend. Now press F12 (or ctrl+i) and you will see the so-called developer’s tools.
Here you can choose between the console output, the DOM elements, debugging functions and possibly styling functions.
For now you are looking for the ‘console’ part. Here you will find an output of messages, together with the .js file they are originating from. Found anything in red color? That will probably need to be fixed. Copy it and paste it together with your issue on github or on the forum.
2.4 - Debugging config.js
The config.js file is a challenge for new users. It is javascript code and gets included into the MM framework in runtime, meaning it needs to be free of any syntax errors.
That is quite a challenge, especially if you’re using the console or simple text editors to edit config.js.
Fortunately there is an easy-to-understand implemented config check (a so-called js linter).
Run this in the Magic Mirror folder
npm run config:check
It will create an output showing all syntax errors.
Move into the respective line in the config.js and find the error. If you use nano as editor for your console, don’t forget the -c flag which includes line numbers
nano -c config/config.js
Here is an example for a common output of the check:
> magicmirror@2.10.1 config:check /home/pi/MagicMirror
> node tests/configs/check_config.js
Checking file... /home/pi/MagicMirror/config/config.js
Line 47 col 5 Expected ']' to match '[' from line 29 and instead saw '{'.
Line 48 col 9 Expected '}' to match '{' from line 12 and instead saw 'disabled'.
Line 48 col 17 Missing semicolon.
Quite a big output for a missing comma.
Try to read and work on the errors one by one. All errors may result from one source, like it does here.
The only I did was missing a comma in line 46.
{
//disabled: true,
module: "MMM-NavigationBar",
position: "bottom_bar",
config: {
}
} <-- HERE the comma is missing!!!
{
So why the output?
The linter reads config.js as a file containing javascript code. It starts with var config = { setting up the config as an object. Then, after declaration of some general config variables there is an array called modules:
modules: [
{
module: "alert",
},
{
module: "updatenotification",
position: "top_bar"
},
...
The array consists of the module entries, each being an object (note the { and }, around every entry). Array items MUST be separated by comma, so every module entry needs to be closed with a },.
When this comma is missing, the linter thinks the array is finished, expecting the ] that closes an array (in this case the modules-array).
That is the reason for the first error message above:
Line 47 col 5 Expected ']' to match '[' from line 29 and instead saw '{'.
All further error messages are logical derivatives of this, and will vanish as soon as you add the comma.
> magicmirror@2.10.1 config:check /home/pi/MagicMirror
> node tests/configs/check_config.js
Checking file... /home/pi/MagicMirror/config/config.js
Your configuration file doesn't contain syntax errors :)
So again, check and clear out the errors one by one. If you don’t know what to do, post the error message and the respective line on the forum.
