Mantis Troubleshooting

If your Mantis device or payload is not behaving as expected, use this step-by-step diagnostic guide to identify and resolve the issue quickly.

1. Mantis Not Working / Host Doesn’t Detect Device

Symptom: You plug Mantis into a USB port, but the host operating system shows no indication of a connected USB device and no keystrokes are typed.

Root Causes & Solutions

• Passive USB Hubs or Unpowered Adapters: Some unpowered USB hubs and cheap USB-C to USB-A adapters fail to negotiate standard 5V USB bus power or drop USB data lines. Connect Mantis directly into a native USB-A motherboard port on your computer.
• OS Driver Binding Delay: When Mantis is connected to a computer for the first time, Windows/macOS/Linux requires 1 to 2 seconds to bind the standard generic USB HID keyboard driver. If your script has no initial `DELAY`, keystrokes fire before the driver is active. Always begin payloads with `DELAY 1500`.
• Testing Hardware Functionality: Disconnect Mantis, hold down the physical Upload button, and reconnect it to USB. If the device is detected as a virtual COM / CDC serial device, the hardware and microcontroller are functioning properly.

2. Payload Not Running / Device Plugs in But Nothing Happens

Symptom: Mantis powers on and the LED illuminates, but no text or shortcuts are injected into the target screen.

Root Causes & Solutions

• Device is in Upload Mode Instead of Attack Mode: The bootloader checks the physical Upload button only once at the exact moment of power-on:
  • Attack Mode (Default): Plug Mantis into USB without touching any buttons. Mantis will immediately boot into Attack Mode and execute the stored payload.
  • Upload Mode: If you hold the Upload button during plug-in, Mantis boots into Upload Mode to receive new code from Karvi Studio and will not execute payloads.
• Empty or Corrupted Flash: If no payload has been uploaded yet, the SPI NOR flash contains blank bytecode. Open Karvi Studio, compile your script, and flash it to the device.
• Target Application Lacks Input Focus: Keystrokes are delivered to the active window. Ensure your payload programmatically opens and focuses the target application (e.g. using `GUI r` followed by `DELAY 600`).

3. Mantis Not Typing / Dropped Keystrokes & Jumbled Text

Symptom: Mantis executes, but characters are skipped, truncated, or typed in the wrong order.

Root Causes & Solutions

• Pacing is Too Fast for Host Processor: Sluggish target machines or virtual machines cannot process keystrokes at maximum speed. Add `SET_SPEED $Normal` or `SET_DELAY 30` to pace keystrokes cleanly.
• Missing Window Animation Delays: Opening dialogs like the Windows Run prompt (`GUI r`) or Terminal requires 400ms – 1000ms for UI rendering. Without a pause, subsequent `STRING` commands will fire before the text input box exists.
• Keyboard Layout Mismatches: Mantis sends standard US QWERTY scan codes. If the target operating system is configured for a regional layout (such as UK, French AZERTY, or German QWERTZ), specific symbols (such as `@`, `#`, `y`, `z`) will map differently. Align the host layout setting or adjust your payload characters accordingly.

4. Syntax Errors & Compiler Diagnostics in Karvi Studio

Symptom: Karvi Studio rejects the script during build time and displays a red diagnostic banner with a line number.

Root Causes & Solutions

• Case Sensitivity: All Mantis commands and structural block keywords must be written in UPPERCASE (e.g. `STRING`, `DELAY`, `LOOP`, `END_LOOP`). Lowercase or mixed-case commands (like `string` or `Delay`) are treated as unknown tokens.
• Unmatched Block Delimiters: Every opening block keyword requires its exact corresponding closing keyword:
  • `LOOP` requires `END_LOOP`
  • `IF … THEN` requires `END_IF`
  • `FUNCTION name()` requires `END_FUNCTION`
  • `BUTTON_DEF` requires `END_BUTTON`
  • `STRING_BLOCK` requires `END_STRING`
• Unknown Modifier Names: Verify modifier spellings against the Keyboard Commands Reference (use `GUI`, `CTRL`, `ALT`, `SHIFT`).

5. Upload Problems & Serial (CDC) COM Port Errors

Symptom: Karvi Studio reports “Cannot open COM port” or fails to find the Mantis device during upload.

Root Causes & Solutions

1. Enter Upload Mode Correctly: Unplug Mantis. Hold down the Upload button on the board. While holding the button, plug Mantis into the USB port. Wait 1 second, then release the button.
2. Select the Correct Port in Studio: In Karvi Studio, open the Port dropdown and verify that the virtual serial device (e.g. `COM3` on Windows or `/dev/ttyACM0` on Linux) is selected.
3. Port Busy in Another Application: Ensure no serial monitor, terminal emulator (PuTTY/TeraTerm), or IDE is holding an open lock on the COM port.

6. Summary of Common Command Mistakes

Still Need Help?

• Browse individual command pages in the Commands Library.
• Review tested templates in the Payload Examples.
• Contact the Karvi engineering team directly at Support.