Configured MCP repository policy must be validated before…

Error message

Configured MCP repository policy must be validated before server creation.

What it means

createMCPServer throws this when no validated McpRepositoryPolicy was passed in options while an unvalidated repository policy is present in configuration (mcpRepositoryPolicyConfigured() returns true). The library refuses to create an MCP server against a backend whose repository access policy was never parsed and validated by McpRepositoryPolicy, because an unvalidated policy could grant unintended repo access. It is a fail-closed safety check.

Solutions

Parse the configured policy with McpRepositoryPolicy (e.g. McpRepositoryPolicy.fromConfig/parse) and pass the validated instance as options.repositoryPolicy.
If unrestricted access is truly intended, explicitly pass McpRepositoryPolicy.unrestricted() so intent is explicit.
Remove or disable the configured repository policy if the server should not be policy-scoped.
Check mcpRepositoryPolicyConfigured() before calling createMCPServer and branch to the validating code path.

Example fix

// before
const server = createMCPServer(backend);
// after
const policy = McpRepositoryPolicy.parse(config.mcpRepositoryPolicy);
const server = createMCPServer(backend, { repositoryPolicy: policy });

Defensive patterns

Strategy: validation

Validate before calling

import { mcpRepositoryPolicyConfigured, McpRepositoryPolicy } from './mcp/policy.js';
if (!options.repositoryPolicy && mcpRepositoryPolicyConfigured()) {
  options.repositoryPolicy = McpRepositoryPolicy.parse(loadConfiguredPolicy());
}
const server = createMCPServer(backend, options);

Type guard

function hasValidatedPolicy(o: { repositoryPolicy?: McpRepositoryPolicy }): o is { repositoryPolicy: McpRepositoryPolicy } {
  return o.repositoryPolicy instanceof McpRepositoryPolicy;
}

Try / catch

try {
  const server = createMCPServer(backend, { repositoryPolicy: validatedPolicy });
} catch (err) {
  if ((err as Error).message.includes('repository policy must be validated')) {
    throw new Error('App bug: pass McpRepositoryPolicy.parse(config) into createMCPServer', { cause: err });
  }
  throw err;
}

Prevention

Always construct the policy via McpRepositoryPolicy before server creation — never call createMCPServer bare when a policy may be configured.
Centralize server creation in one factory that owns policy parsing.
Add a startup assertion that mcpRepositoryPolicyConfigured() === false unless a validated policy is in hand.

When it happens

Trigger: Calling createMCPServer(backend) with no options.repositoryPolicy while config that defines an MCP repository policy exists (e.g. repositoryPolicy set in config file/env). Also passing an explicitly empty options object instead of a validated policy object.

Common situations: Server boot after adding a repository policy to config without wiring it through McpRepositoryPolicy.parse/validate before calling createMCPServer; upgrading versions where policy validation became mandatory; test harnesses constructing the server directly with only a backend.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

AI-assisted analysis of abhigyanpatwari/GitNexus@ac9a4e9abd (2026-09-08). Data as JSON: /api/errors/4c2451ebdee7b5b5. Report an issue: GitHub.

Appendix: source

Thrown at gitnexus/src/mcp/server.ts:116

  const message = error instanceof Error ? error.message : 'Unknown error';
  const code =
    typeof error === 'object' && error !== null && 'code' in error
      ? (error as { code: unknown }).code
      : undefined;
  return typeof code === 'string' ? `Error [${code}]: ${message}` : `Error: ${message}`;
}

/**
 * Create a configured MCP Server with all handlers registered.
 * Transport-agnostic — caller connects the desired transport.
 */
export function createMCPServer(
  backend: LocalBackend,
  options: { repositoryPolicy?: McpRepositoryPolicy } = {},
): Server {
  const readOnly = resolveMcpReadOnlyMode();
  if (!options.repositoryPolicy && mcpRepositoryPolicyConfigured()) {
    throw new Error('Configured MCP repository policy must be validated before server creation.');
  }
  const repositoryPolicy = options.repositoryPolicy ?? McpRepositoryPolicy.unrestricted();
  const scopedBackend = repositoryPolicy.scopeBackend(backend);
  const server = new Server(
    {
      name: 'gitnexus',
      version: packageVersion(),
    },
    {
      capabilities: {
        tools: {},
        resources: {},
        prompts: {},
      },
    },
  );

  // Handle list resources request

View on GitHub (pinned to ac9a4e9abd)