gethomepage/homepage · error · Error

Unsupported config file '${file}'. Supported files: ${CONFIG

Error message

Unsupported config file '${file}'. Supported files: ${CONFIG_FILES.join(", ")}

What it means

Thrown by the MCP server's config-file guard when a caller names a file that isn't in the hardcoded CONFIG_FILES allowlist (settings.yaml, services.yaml, bookmarks.yaml, widgets.yaml, docker.yaml, kubernetes.yaml, proxmox.yaml, custom.css, custom.js). It exists to keep MCP reads/writes inside Homepage's known config surface.

Source

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

      ...(data ? { data } : {}),
    },
  };
}

function textContent(text) {
  return {
    content: [
      {
        type: "text",
        text,
      },
    ],
  };
}

function assertKnownConfigFile(file) {
  if (!CONFIG_FILES.includes(file)) {
    throw new Error(`Unsupported config file '${file}'. Supported files: ${CONFIG_FILES.join(", ")}`);
  }
}

function configPath(file) {
  assertKnownConfigFile(file);
  return join(CONF_DIR, file);
}

function fileExists(file) {
  return existsSync(configPath(file));
}

function readConfig(file) {
  const path = configPath(file);
  return existsSync(path) ? readFileSync(path, "utf8") : "";
}

function parseYamlConfig(file) {

View on GitHub (pinned to b6dca1ae03)

Solutions

1. Use one of the listed filenames exactly (case-sensitive, .yaml not .yml).
2. Call list_config_files first to see the allowlist at runtime.
3. Don't pass paths or query strings — only the bare filename.
4. If you genuinely need a new config file, it must be added to CONFIG_FILES in homepage-mcp.js first.

Example fix

// before
{ "file": "settings.yml" }

// after
{ "file": "settings.yaml" }

const CONFIG_FILES = ['settings.yaml','services.yaml','bookmarks.yaml','widgets.yaml','docker.yaml','kubernetes.yaml','proxmox.yaml','custom.css','custom.js'];
function isKnownConfigFile(file) {
  return CONFIG_FILES.includes(file);
}
// before calling read/write:
if (!isKnownConfigFile(file)) throw new Error(`Use one of: ${CONFIG_FILES.join(', ')}`);

function isKnownConfigFile(file) {
  return typeof file === 'string' && CONFIG_FILES.indexOf(file) !== -1;
}

When it happens

Trigger: assertKnownConfigFile(file) is called from configPath(), readConfig(), write_config_file, validate_config_file, or resources/read, and the passed filename is not in CONFIG_FILES. e.g. tool call `read_config_file` with file='settings.yml', 'services.json', '../settings.yaml', or 'custom.html'.

Common situations: Client uses .yml extension instead of .yaml; caller tries a relative path or directory traversal; typo in filename; user assumes a file exists (e.g. 'theme.yaml') that Homepage never supported; MCP client auto-suggests an unrelated filename.

Related errors

• content must be a string
• ${name} must be an object
• group must be a non-empty string
• name must be a non-empty string
• services.yaml must contain a top-level array

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