How to Fix an IBM Blockchain Extension Local Fabric Startup Error with JavaScript

When I first tried running the IBM Blockchain Platform Extension in VS Code, I ran into a frustrating issue: the Local Fabric runtime refused to start. The error message looked like this:

[INFO] 'generate.cmd' is not recognized as an internal or external command,
[INFO] operable program or batch file.
[ERROR] Failed to start Local Fabric: Error: Failed to execute command "cmd" with arguments "/c, generate.cmd" return code 1

At first glance, it seemed like the extension itself was broken. But after digging in, I realized it was actually a path and environment issue with the generate.cmd script.

My Environment

Here’s the setup I was working with:

• Windows 10
• VS Code v1.38.1
• Node.js v10.15.3, npm v6.4.1
• Docker v19.03.5, docker-compose v1.25.4
• IBM Blockchain Platform extension v1.0.20

First Step Reproducing the Error With Code

To understand what was happening, I wrote a small Node.js script (start-local-fabric.js) that tries to run the same generate.cmd the extension expects. If the script doesn’t exist, it prints a friendly diagnostic message.

// start-local-fabric.js
const { spawn } = require('child_process');
const path = require('path');
const fs = require('fs');

const envDir = path.join(process.env.USERPROFILE || '', '.fabric-vscode', 'environments', 'local_fabric');
const script = path.join(envDir, 'generate.cmd');

if (!fs.existsSync(script)) {
  console.error('[DIAG] generate.cmd was not found at:');
  console.error('       ' + script);
  console.error('[FIX ] Recreate the Local Fabric environment or reinstall the extension.');
  process.exit(2);
}

const child = spawn('cmd', ['/c', 'generate.cmd'], {
  cwd: envDir,
  stdio: 'inherit',
  env: process.env
});

child.on('exit', (code) => {
  if (code === 0) {
    console.log('[OK] generate.cmd completed.');
  } else {
    console.error(`[ERR] generate.cmd exited with code ${code}.`);
    console.error('[HINT] If you see "not recognized", the script is missing or quarantined by antivirus.');
  }
  process.exit(code);
});

Running this with node start-local-fabric.js gave me the exact same “not recognized” message, so I knew I had reproduced the extension’s failure.

What This Error Really Mean

When Windows says:

'generate.cmd' is not recognized as an internal or external command

…it literally means the file does not exist in the working directory (or anywhere in PATH). The IBM Blockchain extension expects this script under:

%USERPROFILE%\.fabric-vscode\environments\local_fabric\generate.cmd

If it’s missing or unreadable, the extension will fail.

Common Causes I Found

1. Local Fabric environment folder missing/corrupted
   (deleted, half-created, or moved).
2. Antivirus/endpoint protection quarantined the .cmd file.
3. Wrong working directory when the script is called.
4. Special characters in Windows username causing path resolution issues.
5. Old extension/runtime mismatch, leaving stale files behind.

How I Fix It

Here are the steps I went through in order of speed:

1. Reset Local Fabric runtime
   In VS Code → IBM Blockchain Platform view → Local Fabric Ops → Teardown/Delete environment → then create a new one and start it again.
2. Check if the script exists
   Navigate to %USERPROFILE%\.fabric-vscode\environments\local_fabric\ and confirm generate.cmd is there.
3. Run VS Code with admin rights
   This helped when Docker needed elevated privileges.
4. Whitelist in antivirus
   My antivirus had flagged and removed .cmd. Restoring it solved the problem.
5. Reinstall the extension
   Uninstall, close VS Code, reinstall, and rebuild the environment.

Sanity Checks I Now Run

To avoid surprises, I built some preflight checks:

PowerShell Diagnostic

$envDir = Join-Path $env:USERPROFILE ".fabric-vscode\environments\local_fabric"
$script = Join-Path $envDir "generate.cmd"

Write-Host "Checking Local Fabric..."

if (-not (Test-Path $envDir)) { Write-Host "[MISS] Env dir not found."; }
elseif (-not (Test-Path $script)) { Write-Host "[MISS] generate.cmd not found."; }
else { Write-Host "[OK] generate.cmd exists."; }

docker --version
docker-compose --version

Extra “Practice” Scripts I Built

Along the way, I wrote a few utilities to learn and avoid future pain.

Cross Platform Runner

// generate-cross.js
const { spawn } = require('child_process');
const path = require('path');
const os = require('os');

const envDir = path.join(process.env.USERPROFILE || '', '.fabric-vscode', 'environments', 'local_fabric');
const isWin = os.platform() === 'win32';
const cmd = isWin ? 'cmd' : 'bash';
const args = isWin ? ['/c', 'generate.cmd'] : ['-lc', './generate.sh'];

spawn(cmd, args, { cwd: envDir, stdio: 'inherit' })
  .on('exit', (code) => process.exit(code));

This way, I don’t have to think about whether I’m on Windows or WSL.

Preflight Checker

# preflight.ps1
$need = @("docker","docker-compose","node","npm")
$need | % {
  $v = (& $_ --version) 2>&1
  if ($LASTEXITCODE -ne 0) { Write-Host "[MISS] $_ not on PATH" }
  else { Write-Host "[OK] $_ : $v.Split([Environment]::NewLine)[0]" }
}

$envDir = Join-Path $env:USERPROFILE ".fabric-vscode\environments\local_fabric"
$gencmd = Join-Path $envDir "generate.cmd"
if (Test-Path $gencmd) { Write-Host "[OK] Found generate.cmd" }
else { Write-Host "[MISS] generate.cmd. Recreate Local Fabric in the extension." }

Final Thought

In the end, the error wasn’t as scary as it looked. The problem was simply that Windows couldn’t find generate.cmd, either because it was missing or the environment was corrupted. Once I reset my Local Fabric environment and made sure Docker and the script were in place, everything started working smoothly again.

If you ever hit this same error, don’t panic. Start by checking whether generate.cmd exists, reset your environment, and then use small diagnostic scripts like the ones above to confirm your setup. With a little patience, you’ll be back to deploying chaincode on Local Fabric in no time.