Learn how to diagnose problems in your JavaScript commands and REST API integrations.

If your custom command doesn’t work, prints errors, or behaves unpredictably, this guide walks you through the best debugging process.

Custom commands are pure JavaScript functions, and REST calls use WordPress’s JSON API, so debugging is straightforward once you know where to look.

---

🔹 1. Start With the Browser Console (Most Important Step) #

Open:

Right-click → Inspect → Console

Then run your custom command in the terminal.

Look for any JavaScript error:

Uncaught ReferenceError: mycommand is not defined
Uncaught TypeError: registry.mycmd is not a function
SyntaxError: Unexpected token

If you see any error:

• your add-on script likely failed
• commands won’t register
• help won’t show them
• terminal won’t run them

Fix the JS error first.

---

🔹 2. Confirm Your Script Actually Loaded #

Open:

Inspect → Network → JS

Look for your file:

my-addon.js
custom-commands.js

If the file is missing:

• Enqueue path is wrong
• File not uploaded
• CDN blocked it
• Plugin directory renamed
• Wrong file permissions

If the file is there but greyed out (blocked):

• caching plugin merged/minified it incorrectly
• script blocked by security plugin

Disable:

• JS minification
• Combine JS files
• Defer JS
• Rocket Loader (Cloudflare)

Reload and test again.

---

🔹 3. Check Command Registration Order #

Commands must be registered after the terminal loads.

Wrong:

registry.mycommand = ...

Correct:

window.addEventListener('load', function() {
    CointactedSocialTerminalTerminal.registry.mycommand = function(input) {
        append_line("OK", "system");
    };
});

If you register too early → registry is undefined.

---

🔹 4. Check Your Metadata #

For command to show in help, metadata must be valid.

Example:

CointactedSocialTerminalTerminal.commands_meta.mycommand = {
    group: "ADDON",
    description: "Says hello",
    alias: ["hi"],
    public: true
};

Missing keys can cause help issues.

Common errors:

❌ group name missing
❌ typo in key (e.g., descripton)
❌ setting hidden: true

Fix metadata → reload browser.

---

🔹 5. Test Command Execution Directly in Console #

Before typing in terminal, test the function in console:

CointactedSocialTerminalTerminal.registry.mycommand({ 
    cmd: "mycommand", 
    args: [], 
    raw: "mycommand" 
});

If this works → your function is fine.
If this fails → issue inside your code.

This isolates input parsing from your command logic.

---

🔹 6. Debug REST API Requests #

If your command uses fetch():

const res = await fetch('/wp-json/myaddon/v1/data');

Open:

Inspect → Network → Fetch/XHR

Click on your request:

Check for:

• Status code (200, 403, 404, 500)
• Response body
• JSON output
• CORS issues
• Nonce/Authentication issues

Common problems:

❌ 404 #

Route not registered:

register_rest_route('myaddon/v1', '/data', [...]

❌ 403 #

Permission callback blocked it:

Fix:

'permission_callback' => '__return_true'

(or proper permission logic)

❌ 500 #

PHP error in callback.

Enable debug:

define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);

Then check:

/wp-content/debug.log

---

🔹 7. Use Console Logging Inside Commands #

Example:

registry.mycmd = function(input) {
    console.log("Input:", input);
    console.log("Args:", input.args);
    console.log("Raw:", input.raw);
    append_line("OK", "system");
};

This helps with:

• argument parsing
• alias handling
• debugging incorrect user syntax

---

🔹 8. Validate Command Arguments #

User may type something your command doesn’t expect.

Example:

random a b

Add validation:

if (input.args.length < 2) {
    return append_line("Usage: random min max", "error");
}

Validate:

• number arguments
• URL formats
• required fields
• JSON structure

---

🔹 9. Check for Other Plugins Overriding Your Command #

If another plugin uses the same command name:

registry.status

Your command will be overwritten.

Check:

help search status

If the description doesn’t match your metadata → you have a naming conflict.

Fix:

• rename your command
• use namespacing: myaddon_status

---

🔹 10. Disable Browser Extensions That Inject Scripts #

Extensions like:

• Grammarly
• LanguageTool
• Password managers
• Privacy blockers
• Web3 blockers

…inject scripts into input fields and can break terminal behavior.

Test in:

• Chrome Incognito
• Firefox Private Window

If command works there → an extension is interfering.

---

🔹 11. Test Add-On With All Other Plugins Disabled #

To isolate the environment:

1. Deactivate all plugins except:
   • Cointacted Social Terminal
   • Your add-on
2. Switch to default theme
3. Test command again

If it works:
Another plugin or theme is breaking scripts.

If it still doesn’t work:
Your command contains a logic or syntax error.

---

🔹 12. Debug Infinite Loops or Freezing #

If command freezes:

while(true) {}

or heavy loops without async:

for (let i=0; i<1e9; i++) {}

Use async functions to break work into chunks:

await new Promise(r => setTimeout(r));

Never block the main thread.

---

🎯 Summary #

To debug custom commands:

✔ Check console for JS errors #

✔ Ensure add-on JS loads correctly #

✔ Register commands after terminal loads #

✔ Validate and test metadata #

✔ Log input arguments #

✔ Test command function directly #

✔ Debug REST responses via Network tab #

✔ Check for syntax mistakes #

✔ Remove naming conflicts #

✔ Test in a clean environment #

Following these steps resolves almost every custom command issue.