VSCode debugger configuration: `localfsMap` not allowed, but still works

[Splines]

Description

🎈 System Info

Click to expand

Ruby LSP Information

VS Code Version

1.100.3

Ruby LSP Extension Version

0.9.27

Ruby LSP Server Version

0.24.1

Ruby LSP Add-ons

• Ruby LSP Rails
• RuboCop

Ruby Version

3.3.8

Ruby Version Manager

rbenv

Installed Extensions

Click to expand

• RunOnSave (0.2.7)
• autopep8 (2025.2.0)
• black-formatter (2025.2.0)
• blender-development (0.0.25)
• code-spell-checker (4.0.47)
• code-spell-checker-french (0.4.3)
• code-spell-checker-german (2.3.3)
• color-picker-universal (2.8.5)
• copilot (1.330.0)
• copilot-chat (0.27.3)
• cpptools (1.25.3)
• debugpy (2025.8.0)
• gitlens (17.1.1)
• hexeditor (1.11.1)
• jupyter (2025.4.1)
• jupyter-renderers (1.1.0)
• lean4 (0.0.207)
• pylint (2025.2.0)
• python (2025.6.1)
• rainbow-csv (3.19.0)
• ruby-lsp (0.9.27)
• rust-analyzer (0.3.2490)
• test-adapter-converter (0.2.1)
• tinymist (0.13.12)
• todo-tree (0.0.226)
• vscode-ansi (1.1.7)
• vscode-eslint (3.0.10)
• vscode-github-actions (0.27.2)
• vscode-just-syntax (0.8.0)
• vscode-markdownlint (0.60.0)
• vscode-pull-request-github (0.110.0)
• vscode-pylance (2025.5.1)
• vscode-python-test-adapter (0.8.2)
• vscode-ruby-test-adapter (0.9.2)
• vscode-settings-cycler (1.0.1)
• vscode-test-explorer (2.22.1)

Ruby LSP Settings

Click to expand

Workspace

{
  "enabledFeatures": {
    "codeActions": true,
    "diagnostics": true,
    "documentHighlights": true,
    "documentLink": true,
    "documentSymbols": true,
    "foldingRanges": true,
    "formatting": true,
    "hover": true,
    "inlayHint": true,
    "onTypeFormatting": true,
    "selectionRanges": true,
    "semanticHighlighting": true,
    "completion": true,
    "codeLens": true,
    "definition": true,
    "workspaceSymbol": true,
    "signatureHelp": true,
    "typeHierarchy": true
  },
  "rubyVersionManager": {
    "identifier": "rbenv"
  },
  "formatter": "rubocop",
  "enableExperimentalFeatures": true
}

User

{
  "enabledFeatures": {
    "codeActions": true,
    "diagnostics": true,
    "documentHighlights": true,
    "documentLink": true,
    "documentSymbols": true,
    "foldingRanges": true,
    "formatting": true,
    "hover": true,
    "inlayHint": true,
    "onTypeFormatting": true,
    "selectionRanges": true,
    "semanticHighlighting": true,
    "completion": true,
    "codeLens": true,
    "definition": true,
    "workspaceSymbol": true,
    "signatureHelp": true,
    "typeHierarchy": true
  },
  "featuresConfiguration": {},
  "addonSettings": {},
  "rubyVersionManager": {
    "identifier": "rbenv"
  },
  "customRubyCommand": "",
  "formatter": "rubocop",
  "linters": null,
  "bundleGemfile": "",
  "testTimeout": 30,
  "branch": "",
  "pullDiagnosticsOn": "both",
  "useBundlerCompose": false,
  "bypassTypechecker": false,
  "rubyExecutablePath": "",
  "indexing": {},
  "erbSupport": true,
  "featureFlags": {
    "all": true
  },
  "sigOpacityLevel": "1",
  "enableExperimentalFeatures": true
}

🎈 Problem description

We use the following launch.json configuration.

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Debug Ruby in Docker",
            "type": "ruby_lsp",
            "request": "attach",
            "debugPort": 13254,
            "localfsMap": "/usr/src/app/:${workspaceFolder}",
        },
    ]
}

And start the debugger as following in the entrypoint script of a Docker container:

RUBY_DEBUG_OPEN=true RUBY_DEBUG_NONSTOP=true RUBY_DEBUG_HOST="0.0.0.0" RUBY_DEBUG_PORT=13254 bundle exec bin/rails s -p 3000 -b '0.0.0.0' &> >(tee -a /usr/src/app/log/runtime.log)

For the launch.json configuration, VSCode gives this warning:

Property localfsMap not allowed.

However, this property works just fine, even though I've uninstalled the VSCode rdbg Ruby Debugger extension which offers this property in their configuration. (I also made sure to restart VSCode completely):

localfsMap: Specify pairs of remote root path and local root path like /remote_dir:/local_dir if sharing the same source repository with local and remote computers.

Without this property, the debugger can attach, but my breakpoints are not recognized. Then, I simply detach the debugger, add the localfsMap property to the config and attach the debugger again and suddenly my breakpoints are recognized. When I now remove this property, it seems to be cached until the next restart of VSCode.

This is a bit weird since nowhere in your codebase do I find the word localfsMap. Do you somehow still support this by means of an external gem? I'm a bit confused, but won't complain since it works fine for us, even though VSCode shows the warning.

[vinistock]

Thanks for the report. VS Code warns that the option is not allowed because we didn't declare it in our package.json, so it doesn't know about the option.

It still works because whatever you put in your launch configurations, we pass to the Ruby debug gem (which handles all of the options).

We need to go through all of the different options supported by the gem and ensure that we have registered them in the package.json so that it doesn't look like it's unsupported.