garrytan/gstack · error

Unknown host '${arg}'. Valid hosts: ${ALL_HOST_NAMES.join(',

Error message

Unknown host '${arg}'. Valid hosts: ${ALL_HOST_NAMES.join(', ')}

What it means

Thrown by resolveHostArg() when a CLI argument matches neither a canonical host name in HOST_CONFIG_MAP nor any value in any host config's cliAliases array. It is the user-facing counterpart to 305: the CLI entry point canonicalizes free-text args, and anything unrecognized is rejected with the full valid-host list. Aliases (e.g. 'agents'→'codex', 'droid'→'factory') must be declared per-config via cliAliases.

Source

Thrown at hosts/index.ts:56

    throw new Error(`Unknown host '${name}'. Valid hosts: ${ALL_HOST_NAMES.join(', ')}`);
  }
  return config;
}

/**
 * Resolve a host name from a CLI argument, handling aliases.
 * e.g., 'agents' → 'codex', 'droid' → 'factory'
 */
export function resolveHostArg(arg: string): string {
  // Direct name match
  if (HOST_CONFIG_MAP[arg]) return arg;

  // Alias match
  for (const config of ALL_HOST_CONFIGS) {
    if (config.cliAliases?.includes(arg)) return config.name;
  }

  throw new Error(`Unknown host '${arg}'. Valid hosts: ${ALL_HOST_NAMES.join(', ')}`);
}

/**
 * Get hosts that are NOT the primary host (Claude).
 * These are the hosts that need generated skill docs.
 */
export function getExternalHosts(): HostConfig[] {
  return ALL_HOST_CONFIGS.filter(c => c.name !== 'claude');
}

// Re-export individual configs for direct import
export { claude, codex, factory, kiro, opencode, slate, cursor, openclaw, hermes, gbrain };

View on GitHub (pinned to 94993f7401)

Solutions

1. Use one of the names or aliases listed in the error message.
2. Check the casing — matching is case-sensitive.
3. If the alias should be valid, add it to the relevant host config's cliAliases array.
4. When renaming a host, keep the old name in cliAliases to avoid breaking existing scripts.

Example fix

// before — undeclared alias
resolveHostArg('robot'); // throws

// after — add the alias in hosts/factory.ts (or similar)
export default { name: 'factory', cliAliases: ['droid', 'robot'], ... };

import { ALL_HOST_NAMES, HOST_CONFIG_MAP, ALL_HOST_CONFIGS } from './hosts';
const VALID_ARGS = new Set<string>([
  ...ALL_HOST_NAMES,
  ...ALL_HOST_CONFIGS.flatMap(c => c.cliAliases ?? []),
]);
function isValidHostArg(arg: string): boolean {
  return VALID_ARGS.has(arg);
}

function isHostArg(arg: string): boolean {
  if (HOST_CONFIG_MAP[arg]) return true;
  return ALL_HOST_CONFIGS.some(c => c.cliAliases?.includes(arg));
}

try {
  return resolveHostArg(arg);
} catch (e) {
  if (e instanceof Error && e.message.startsWith('Unknown host')) {
    // Suggest the closest match
    const suggest = closestMatch(arg, ALL_HOST_NAMES);
    throw new Error(`Unknown host '${arg}'. Did you mean '${suggest}'?`);
  }
  throw e;
}

When it happens

Trigger: resolveHostArg(arg) where arg is misspelled, uppercase, an undeclared alias, or a host that does not exist. The function checks direct name match first, then iterates cliAliases; failing both throws.

Common situations: User types '--host Codex' (case) or '--host agent' (typo); an alias was intended but never added to the host config's cliAliases; a renamed host whose old name was not retained as an alias for back-compat.

Related errors

• Unknown host '${name}'. Valid hosts: ${ALL_HOST_NAMES.join('
• Usage: screenshot --clip x,y,width,height — all must be numb
• gbrain sources list returned no JSON
• Unsafe value for ${context}: ${val}
• Skill name is empty.

AI-assisted analysis of garrytan/gstack@94993f7401 (2026-08-12). Data as JSON: /api/errors/41142ce296fea0e7. Report an issue: GitHub.