headroomlabs-ai/headroom · error · Error

invalid plugin name: ${JSON.stringify(name)}

Error message

invalid plugin name: ${JSON.stringify(name)}

What it means

Error "invalid plugin name: ${JSON.stringify(name)}" thrown in headroomlabs-ai/headroom.

Source

Thrown at sdk/typescript/src/paths.ts:252

  return joinPath(workspaceDir(), `.beacon_lock_${Math.trunc(port)}`);
}

// ---------------------------------------------------------------------------
// Per-resource helpers -- config bucket
// ---------------------------------------------------------------------------

export function modelsConfigPath(): string {
  if (!isNode()) return "";
  return joinPath(configDir(), "models.json");
}

// ---------------------------------------------------------------------------
// Plugin-author entry points
// ---------------------------------------------------------------------------

function assertPluginName(name: string): void {
  if (!name || name.includes("/") || name.includes("\\")) {
    throw new Error(`invalid plugin name: ${JSON.stringify(name)}`);
  }
}

export function pluginConfigDir(pluginName: string): string {
  assertPluginName(pluginName);
  if (!isNode()) return "";
  return joinPath(configDir(), "plugins", pluginName);
}

export function pluginWorkspaceDir(pluginName: string): string {
  assertPluginName(pluginName);
  if (!isNode()) return "";
  return joinPath(workspaceDir(), "plugins", pluginName);
}

View on GitHub (pinned to 322425c43b)

Solutions

1. Use a plugin name containing only valid path-safe characters (no path separators, '..', or control characters)
2. Check the provided name ${JSON.stringify(name)} against the plugin naming rules

When it happens

Trigger: Raised when a plugin name fails validation, typically because it contains characters that would be unsafe in a filesystem path.

Common situations: See trigger scenarios.

AI-assisted analysis of headroomlabs-ai/headroom@322425c43b (2026-08-15). Data as JSON: /api/errors/b9190adf0f94bf2a. Report an issue: GitHub.