Troubleshooting

Tools reply "Run tb_login" or "No credentials"

Issue

Every tool except tb_login replies with something like:

No TestingBot credentials configured. Run the tb_login tool to authenticate.

Cause

The server is running in degraded mode. It could not find usable credentials, so it disables every tool that talks to TestingBot and only keeps tb_login available. The server looks for credentials in this order:

1. Environment variables: both TESTINGBOT_KEY and TESTINGBOT_SECRET must be set. Setting only one is not enough.
2. Credentials file: ~/.testingbot/credentials, written automatically after a successful tb_login.
3. Degraded mode: neither of the above was found.

Fix

Pick whichever fits your environment:

• Interactive desktop: ask your agent to run the tb_login tool. A browser opens, you click Authorize, and credentials are captured automatically, with nothing pasted. No restart is needed; the next tool call will work.
• SSH / remote / headless: run tb_login with mode set to device (see below).
• CI or a shared config: set the key and secret in your client's env block. Generate them at testingbot.com/members/user/edit.

{
  "mcpServers": {
    "testingbot": {
      "command": "npx",
      "args": ["-y", "@testingbot/mcp-server@latest"],
      "env": { "TESTINGBOT_KEY": "<key>", "TESTINGBOT_SECRET": "<secret>" }
    }
  }
}

For the full authentication model (loopback vs device flow, profiles, and where credentials are stored), see Authentication.

Requested real device is unavailable, busy, or the wrong OS version

Issue

You asked to automate a physical device (for example "open Safari on a real iPhone 15 Pro") and the agent comes back with guidance instead of a running session, it tells you the device is busy, the OS version isn't offered, or suggests an alternative.

Cause

When tb_openBrowser is called with realDevice: true, the server runs a pre-flight check against the real-device cloud before consuming any minutes. If the exact device/version combination is currently in use or simply not offered, it returns advice without starting a session, so you don't burn time on a session that can't start.

Fix

• Wait and retry: physical devices are shared. If the device is just busy, try again shortly.
• Pick an offered version: ask the agent to list devices first (getDevices) and choose an available OS version. You can also browse the live availability at https://testingbot.com/device.
• Use an emulator or simulator instead: drop realDevice (it defaults to false) to run the same mobile browser on an emulator/simulator. These are cheaper and far more plentiful, and are usually fine unless you specifically need real hardware (GPU, sensors, real Chrome/Safari).

The screenshot doesn't show in my chat

Issue

You asked for a screenshot with tb_screenshot, the tool reports success, but no image appears in your AI client's chat window.

Cause

tb_screenshot returns the screenshot two ways: an inline image and a saved PNG file with a clickable file:// link. Many MCP clients do not render inline tool images in the conversation, so the picture is captured correctly, your client just isn't displaying it.

Fix

• Open the saved file: the tool always returns a file:// link to the PNG it wrote. Click or open that path to view the screenshot.
• Control where it's written: pass a savePath (a .png file path or a directory) so the image lands somewhere you can find easily. Without it, the server saves to your OS temp directory.

Example prompt:

"Take a screenshot of the current page and save it to ~/Desktop/checkout.png"

Browser login didn't open, or I'm on SSH / a remote host

Issue

You ran tb_login but no browser window appeared, or you're working over SSH, in a container, or in a web-based client where opening a local browser isn't possible.

Cause

The default tb_login mode is auto, which prefers the loopback flow (RFC 8252): it opens a browser on your machine and captures credentials on a local 127.0.0.1 callback. On a headless or remote host there is no local browser to open, so that flow can't complete.

Fix

Use the device-code flow (RFC 8628) by running tb_login with mode set to device. The tool prints a short code; open https://testingbot.com/device on any device, enter the code, and click Authorize. The flow is resumable, if it times out, just run tb_login again to finish.

You can also set a default with the TESTINGBOT_AUTH_MODE environment variable. More detail on Authentication.

Node version errors

Issue

The server fails to start, or npx throws syntax/engine errors when launching @testingbot/mcp-server.

Cause

The TestingBot MCP server requires a modern Node.js runtime. Older versions lack APIs the server (and its bundled @testingbot/automation-mcp) depend on.

Fix

Install Node.js 18 or newer (20+ recommended). Check your version, then confirm the install command your client uses:

node --version
# should print v18.x or higher (v20+ recommended)

npx -y @testingbot/mcp-server@latest

If your MCP client uses a different Node than your shell (common with version managers like nvm), point the client's command at the correct Node binary, or make sure the right Node is first on your PATH.

Sessions seem stuck or keep using minutes

Issue

An automation session appears to be running long after you're done with it, and you're worried it's still consuming TestingBot minutes.

Cause

Each tb_openBrowser call starts a real session that stays open until it's closed. If the agent moved on without calling tb_closeBrowser, the session can linger.

Fix

• List active sessions: ask the agent to run tb_listSessions to see everything currently open.
• Close them: run tb_closeBrowser with the sessionId to end a session and free minutes immediately.
• Stop an account-level test: for a non-automation session you can use stopTest with its sessionId.

Idle sessions auto-close after a period of inactivity, so a forgotten session won't run indefinitely. but closing explicitly is faster and avoids wasted minutes. A good habit is to end a workflow with a prompt like "close all my open browser sessions".

Where are my logs

Issue

A test failed and you want to see what happened, selenium, browser, Appium or VM logs for the session.

Cause

Session logs live on TestingBot, not on your machine. The MCP server exposes them through the getFailureLogs tool rather than writing them locally.

Fix

Ask the agent to fetch logs for the session with getFailureLogs. You can filter by log type and limit the volume:

A typical debugging flow is getTests → getTestDetails → getFailureLogs. See the worked example under Use cases & workflows, or the full parameter list in the Tool reference.

Noisy output or WDIO_LOG_LEVEL

Issue

You're seeing unexpectedly verbose WebDriver output, or conversely you want more detail when diagnosing an automation problem.

Cause

The bundled automation layer uses a WebDriver client whose verbosity is controlled by WDIO_LOG_LEVEL. The server sets this to silent by default so your client's chat stays clean, so this rarely needs changing.

Fix

To get more detail while debugging, set WDIO_LOG_LEVEL in your client's env block (for example error, warn, info or debug). Leave it at silent for normal use.

{
  "mcpServers": {
    "testingbot": {
      "command": "npx",
      "args": ["-y", "@testingbot/mcp-server@latest"],
      "env": {
        "TESTINGBOT_KEY": "<key>",
        "TESTINGBOT_SECRET": "<secret>",
        "WDIO_LOG_LEVEL": "info"
      }
    }
  }
}