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

Provide name as a non-empty trimmed string, e.g. "Grafana".

gethomepage/homepage · error · Error

name must be a non-empty string

Error message

name must be a non-empty string

What it means

Thrown by addService when the `name` argument is missing or not a non-empty string. The name becomes the service's display key inside its group, so an empty/missing name is rejected before touching YAML.

Source

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

  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");
  }

  const groupName = args.group.trim();
  const serviceName = args.name.trim();
  const serviceConfig = args.service ?? {};

View on GitHub (pinned to b6dca1ae03)

Solutions

Provide name as a non-empty trimmed string, e.g. "Grafana".
Use a distinct name within the target group — duplicates are caught later but a clear name avoids churn.
Verify the tool-call arguments include the `name` key.
Avoid array/object values for name.

Example fix

// before
{ "group": "Monitoring", "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.name)) {
  return { isError: true, message: 'name is required' };
}

Type guard

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

Prevention

Treat name as required alongside group when calling add_service.
Validate before sending to get cleaner MCP error messages.
Avoid duplicate names within the same group.
Keep names short and human-readable.

When it happens

Trigger: add_service tool called with args.name undefined/null/non-string/empty/whitespace-only. Guard: `typeof args.name !== "string" || !args.name.trim()`.

Common situations: Client omits name thinking only the URL matters; sends an empty string; uses the URL as the name but forgets to populate the field; whitespace from a templated payload.

Related errors

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