
Debugging broken userscripts or viewing error logs in Tampermonkey involves using the Tampermonkey Dashboard, the built-in Script Editor, and your browser's Developer Tools (F12).
1.Check the Tampermonkey Dashboard Action Log:Reveals top-level execution errors and execution status.
-
Open the Tampermonkey Dashboard from the browser extensions menu.
-
Go to the Settings tab.
-
Under Config mode, select Advanced.
-
Scroll down to the Logging section:
-
Set Log Level to Debug or Verbose.
-
-
Switch to the Action Log tab at the top of the dashboard to view background error events, script injection failures, or permission blocks.
2.Inspect page console errors via Browser DevTools:Displays real-time JavaScript runtime exceptions and console logs.
Userscript execution errors (such as Uncaught TypeError or failed GM_xmlhttpRequest calls) print directly to the webpage's developer console.
-
Navigate to the webpage where the script runs (e.g.,
[xbox.com/play](https://xbox.com/play)). -
Press
F12(orCtrl + Shift + I/Cmd + Option + I) to open Developer Tools. -
Click the Console tab.
-
In the console filter bar, ensure Errors and Warnings are checked.
-
Look for error messages prefixed with
[Tampermonkey]or the name of your script.
3.Use the built-in Script Editor Debugger:Enables syntax checking and breakpoint step-debugging.
-
In the Tampermonkey Dashboard, click the script's name to open the code editor.
-
Check the left gutter for red markers or warning icons indicating syntax errors or missing
@grantrules. -
Add a
debugger;statement directly inside the code block you want to inspect:
JavaScript
// Example: Step-debug inside an xCloud function
function modifyStreamSettings() {
debugger; // Browser execution pauses here when DevTools is open
let settings = GM_getValue("customSettings");
console.log("Current Settings:", settings);
}
-
Open the webpage with DevTools (F12) open. When the script executes, execution will automatically pause on the
debugger;line, allowing you to step through code and inspect variables in the Sources tab.
4.Inspect GM_ API calls and Network requests:Uncovers failures in cross-domain requests or background scripts.
If a script fails while fetching external data:
-
Open DevTools (
F12) and switch to the Network tab. -
Filter by Fetch/XHR.
-
If the script uses
GM_xmlhttpRequest, check if missing headers or@connectrules in the script header are causing permission blocks:
JavaScript
// ==UserScript==
// @name Debug Script
// @match https://xbox.com/*
// @connect api.github.com
// @grant GM_xmlhttpRequest
// ==UserScript==
Common Tampermonkey Errors & Quick Fixes
Console Error
Cause
Fix
GM_setValue is not defined
Missing header permission
Add // @grant GM_setValue to the script metadata header block.
Refused to connect / Content Security Policy (CSP)
Webpage CSP blocks standard fetch()
Replace window.fetch calls with GM_xmlhttpRequest inside the script.
Script does not run
@match or @include pattern mismatch
Ensure URL pattern matches target page (e.g., [https://www.xbox.com/](https://www.xbox.com/)* vs [https://xbox.com/](https://xbox.com/)*).
Comments
Post a Comment
Do not insert clickable links or your comment will be deleted. Checkbox Send me notifications to be notified of new comments via email.