gethomepage/homepage · error · Error

Unsupported resource URI. Use homepage://config/<filename>.

Error message

Unsupported resource URI. Use homepage://config/<filename>.

What it means

Thrown by parseConfigResourceUri when an MCP resources/read request supplies a URI that doesn't start with the expected `homepage://config/` prefix. Homepage's MCP server only exposes config files under that URI scheme.

Source

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

    writable: writeEnabled(),
    description: FILE_DESCRIPTIONS[file],
    docs: DOC_LINKS[file],
  }));
}

function configResource(file) {
  return {
    uri: `homepage://config/${file}`,
    name: file,
    description: FILE_DESCRIPTIONS[file],
    mimeType: file.endsWith(".yaml") ? "application/yaml" : "text/plain",
  };
}

function parseConfigResourceUri(uri) {
  const prefix = "homepage://config/";
  if (!uri?.startsWith(prefix)) {
    throw new Error("Unsupported resource URI. Use homepage://config/<filename>.");
  }
  const file = uri.slice(prefix.length);
  assertKnownConfigFile(file);
  return file;
}

function toolDefinitions() {
  return [
    {
      name: "list_config_files",
      description:
        "List Homepage config files this server understands, whether they currently exist, and where their docs live.",
      inputSchema: {
        type: "object",
        properties: {},
      },
    },
    {

View on GitHub (pinned to b6dca1ae03)

Solutions

1. Use the exact URI form homepage://config/<filename>, e.g. homepage://config/services.yaml.
2. Call resources/list first — it returns the exact URIs the server accepts.
3. Pass only filenames from CONFIG_FILES after the prefix.
4. If extending the server, register new resources via configResource() so they advertise the same scheme.

Example fix

// before
{ "uri": "homepage://services.yaml" }

// after
{ "uri": "homepage://config/services.yaml" }

function buildConfigUri(file) {
  const prefix = 'homepage://config/';
  if (typeof file !== 'string' || !file.startsWith(prefix)) {
    throw new Error(`URI must start with ${prefix}`);
  }
  return file;
}

function isConfigResourceUri(uri) {
  return typeof uri === 'string' && uri.startsWith('homepage://config/');
}

When it happens

Trigger: resources/read with message.params.uri that doesn't `startsWith('homepage://config/')`. Examples: 'homepage://services.yaml', 'file:///settings.yaml', 'homepage://config' (no trailing slash+name), or an empty/null uri (optional chaining makes undefined fail the startsWith).

Common situations: MCP client builds URIs from a template that omits the `config/` segment; client uses a plain path or file:// URI; caller guesses the scheme; URI was passed as a non-string.

Related errors

• Unsupported config file '${file}'. Supported files: ${CONFIG
• ${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/014b87b351834fab. Report an issue: GitHub.