What causes "group must be a non-empty string" in gethomepage/homepage?

Provide group as a non-empty trimmed string, e.g. "Infrastructure".

gethomepage/homepage · error · Error

group must be a non-empty string

Error message

group must be a non-empty string

What it means

Thrown by addService when the `group` argument is missing or not a non-empty string. Each service in Homepage's services.yaml must live inside a named group, so the group identifier is mandatory.

Source

Thrown at src/utils/mcp/homepage-mcp.js:180

      ...textContent("Writing is disabled. Set HOMEPAGE_MCP_ALLOW_WRITE=true to enable MCP config edits."),
    };
  }
  return null;
}

function dumpYamlConfig(file, content) {
  const dumped = yaml.dump(content, { lineWidth: -1, noRefs: true });
  mkdirSync(CONF_DIR, { recursive: true });
  writeFileSync(configPath(file), dumped, "utf8");
  return dumped;
}

function addService(args) {
  const disabled = ensureWriteEnabled();
  if (disabled) return disabled;

  if (typeof args.group !== "string" || !args.group.trim()) {
    throw new Error("group must be a non-empty string");
  }
  if (typeof args.name !== "string" || !args.name.trim()) {
    throw new Error("name must be a non-empty string");
  }

  const validation = validateYaml("services.yaml", readConfig("services.yaml"));
  if (!validation.valid) {
    return {
      isError: true,
      ...textContent(JSON.stringify(validation, null, 2)),
    };
  }

  const services = parseYamlConfig("services.yaml");
  if (!Array.isArray(services)) {
    throw new Error("services.yaml must contain a top-level array");
  }

View on GitHub (pinned to b6dca1ae03)

Solutions

Provide group as a non-empty trimmed string, e.g. "Infrastructure".
If the group doesn't exist yet it will be created automatically — pick a clear human-readable name.
Check the tool-call arguments object actually contains a `group` key.
Avoid leading/trailing spaces; they're stripped but indicate a client bug.

Example fix

// before
{ "name": "Grafana", "service": { "href": "http://grafana:3000" } }

// after
{ "group": "Monitoring", "name": "Grafana", "service": { "href": "http://grafana:3000" } }

Defensive patterns

Strategy: validation

Validate before calling

function isNonEmptyString(v) {
  return typeof v === 'string' && v.trim().length > 0;
}
if (!isNonEmptyString(args.group)) {
  return { isError: true, message: 'group is required' };
}

Type guard

function isNonEmptyString(v) {
  return typeof v === 'string' && v.trim().length > 0;
}

Prevention

Make group a required field in your MCP client schema.
Trim and validate identifiers before sending.
Reuse a single helper for all 'non-empty string' arg checks.
Return isError results instead of throwing when building MCP tool wrappers.

When it happens

Trigger: add_service tool called with args.group undefined, null, a number, an array, an empty string, or a whitespace-only string. The check is `typeof args.group !== "string" || !args.group.trim()`.

Common situations: MCP client omits group; passes an empty string; uses a numeric id; sends whitespace; confuses group with the service name.

Related errors

AI-assisted analysis of gethomepage/homepage@b6dca1ae03 (2026-08-13). Data as JSON: /api/errors/2a5b8a27271b4139. Report an issue: GitHub.