Blog

VS Code BoxLang Extension: Debugging BoxLang in CommandBox

Maria Jose Herrera September 26, 2024

Spread the word

Maria Jose Herrera

September 26, 2024

Spread the word


Share your thoughts

Debugging a CommandBox BoxLang Server

So you’ve installed CommandBox and are running the latest BoxLang server like a boss. You open up your browser and are met with an error message. This looks like a job for, you guessed it, the BoxLang VS Code Debugger!

Hooking VS Code Up To Your Server

Connecting your debugger to an external my seem intimidating but CommandBox + VS Code makes this pretty straightforward.

Configuring CommandBox

To start we will need to make sure our server is configured properly. You can do this one of two ways.

We can add JVMArgs to the CLI

server start cfengine=boxlang javaVersion=openjdk21_jdk JVMArgs='-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=8888'

The alternative approach is to add some configuration to our server.json.

{
  "JVM": {
    "args": "-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=8888",
    "javaVersion": "openjdk21_jdk"
  }
}

In these examples I’ve used port 8888 as the port we want the debugger to connect to control the CommandBox server through. You can specify whatever open port you want. You just need to make sure that you use the same one at every step.

Once you start your server it should run as normal.

Configuring VS Code

Now that your server is configured, we need to setup VS Code. We will need to update your .vscode/launch.json. If you don’t see this file, you can create it yourself and VS Code will pick it up.

We want the launch.json to look something like

{
  "configurations": [
    {
      "name": "Debug CommandBox",
      "type": "boxlang",
      "request": "attach",
       // make sure this is the same value you configured your server with            
      "serverPort": "8888"
    }
  ]
}

Starting a Debug Session

At this point your server is configured, it’s running, and you have just added a launch configuration. The next step is to run the debugger. All we need to do is open up the debug tab in our side-panel and select the correct configuration.

ContentBox

Now that we have everything setup all we need to do is press “play” or hit f5 and VS Code will fire up the BoxLang debugger and attach to your BoxLang server.

Conclusion

We’ve covered how easy it is to setup a BoxLang server and start debugging it with the BoxLang VS Code extension and CommandBox. Hopefully this will be a useful addition to your workflow.

Add Your Comment

Recent Entries

BoxLang AI 3.7: Profiles, Embeddings Defaults and MCP Rate Limiting

BoxLang AI 3.7: Profiles, Embeddings Defaults and MCP Rate Limiting

Ortus Solutions announces the release of BoxLang AI 3.7. Name a provider, model, params and API key once, then pick it by name for a call, an agent, or a single agent run. Embeddings get their own defaults, MCP servers you build get rate limiting and trusted proxies, and a handful of important fixes land along the way.

Luis Majano
Luis Majano
November 05, 2026
BoxLang  1.19.0: See Everything Your Code Does

BoxLang 1.19.0: See Everything Your Code Does

Ortus Solutions today announces the release of BoxLang 1.19.0, the software productivity platform for building, modernizing and running applications, with developers and AI agents working together. This release is about observability: built-in code coverage and execution profiling, the missing post-invocation events for BIFs, and new query and transaction events, and it pairs with the new BxLens beta, the debug bar and ops console that exposes hotspots and bytecode profilers. It also adds your own global settings in boxlang.json, static method interception, raw binary HTTP streaming and a lot of hardening across JDBC, Java interop and CFML compatibility.

Luis Majano
Luis Majano
November 05, 2026
Build AI Agents with Less Configuration: Join Luis Majano in Málaga

Build AI Agents with Less Configuration: Join Luis Majano in Málaga

Learn how to define, build, and run AI agents with BxAgents in a hands-on session organized by Malaga-AI and sponsored by Ortus Solutions! 🚀

Building an AI agent means connecting instructions, models, tools, and application logic. A clear project structure makes those pieces easier to organize and develop.

Maria Jose Herrera
Maria Jose Herrera
November 04, 2026