# Common Failure Modes in Deepwiki MCP: How to Troubleshoot Timeout Errors and Validation Issues

> Troubleshoot Deepwiki MCP timeout errors and validation issues by adjusting request timeouts and concurrency. Learn common failure modes and their solutions for the regenrek/deepwiki-mcp repository.

- Repository: [Kevin Kern/deepwiki-mcp](https://github.com/regenrek/deepwiki-mcp)
- Tags: how-to-guide
- Published: 2026-02-16

---

**Deepwiki MCP timeouts typically stem from large repository crawls exceeding the default 30-second Undici timeout, which you can resolve by setting `DEEPWIKI_REQUEST_TIMEOUT` to 60000ms or higher and increasing `DEEPWIKI_MAX_CONCURRENCY` to 15-20.**

Deepwiki MCP is an open-source Model Context Protocol (MCP) server that fetches and converts documentation from `deepwiki.com` into Markdown. When working with this tool, you may encounter several common failure modes ranging from schema validation errors to network timeouts. Understanding the root causes of these failures—particularly how to troubleshoot timeout errors in deepwiki-mcp—ensures reliable documentation retrieval even for large repositories.

## Understanding the Request Flow in Deepwiki MCP

The server processes requests through a five-stage pipeline defined in [`src/tools/deepwiki.ts`](https://github.com/regenrek/deepwiki-mcp/blob/main/src/tools/deepwiki.ts) and [`src/lib/httpCrawler.ts`](https://github.com/regenrek/deepwiki-mcp/blob/main/src/lib/httpCrawler.ts):

1. **Input validation** via `FetchRequest.safeParse` in [`src/schemas/deepwiki.ts`](https://github.com/regenrek/deepwiki-mcp/blob/main/src/schemas/deepwiki.ts)
2. **Domain safety** checks ensuring the hostname is exactly `deepwiki.com`
3. **Crawling** via the `crawl` function in [`src/lib/httpCrawler.ts`](https://github.com/regenrek/deepwiki-mcp/blob/main/src/lib/httpCrawler.ts) with configurable concurrency
4. **Network robustness** through a retry loop with exponential backoff
5. **GitHub shortcut resolution** via `resolveRepo` in [`src/utils/resolveRepoFetch.ts`](https://github.com/regenrek/deepwiki-mcp/blob/main/src/utils/resolveRepoFetch.ts)

## Common Failure Modes and Root Causes

### Schema Validation Errors

When the JSON-RPC payload fails `FetchRequest.safeParse` in [`src/tools/deepwiki.ts`](https://github.com/regenrek/deepwiki-mcp/blob/main/src/tools/deepwiki.ts), the server returns an `ErrorEnvelope` with code `VALIDATION`. This typically occurs when required fields like `url` are missing or when `maxDepth` exceeds allowed bounds.

### Domain Not Allowed Errors

The server explicitly checks that the URL hostname equals `deepwiki.com` at lines 96-103 in [`src/tools/deepwiki.ts`](https://github.com/regenrek/deepwiki-mcp/blob/main/src/tools/deepwiki.ts). Supplying any other domain triggers an `ErrorEnvelope` with code `DOMAIN_NOT_ALLOWED`.

### HTTP Fetch Failures

During crawling, [`src/lib/httpCrawler.ts`](https://github.com/regenrek/deepwiki-mcp/blob/main/src/lib/httpCrawler.ts) implements a retry mechanism with `RETRY_LIMIT` set to 3 and `BACKOFF_BASE_MS` set to 250ms. If all retries exhaust, the failure is recorded in the `errors` array of the response envelope, allowing partial success returns rather than total failure.

### GitHub API Resolution Errors

When using single-word shortcuts, `resolveRepo` in [`src/utils/resolveRepoFetch.ts`](https://github.com/regenrek/deepwiki-mcp/blob/main/src/utils/resolveRepoFetch.ts) queries the GitHub Search API. Rate limiting or network issues here can cause resolution failures, though the system falls back to `defaultuser/<keyword>` before potentially surfacing a validation error.

### Timeout Errors

Timeouts represent the most common operational failure. The underlying `fetch` implementation in [`src/lib/httpCrawler.ts`](https://github.com/regenrek/deepwiki-mcp/blob/main/src/lib/httpCrawler.ts) uses Undici with a default 30-second timeout. Large repositories with `maxDepth` > 1 generate many HTTP requests that easily exceed this limit, especially when `DEEPWIKI_MAX_CONCURRENCY` remains at the default value of 5.

## How to Troubleshoot Timeout Errors in Deepwiki MCP

### Increase the Request Timeout

Set the `DEEPWIKI_REQUEST_TIMEOUT` environment variable to extend the Undici timeout beyond the default 30 seconds. The value is specified in milliseconds.

```bash

# In your .env file or shell environment

DEEPWIKI_REQUEST_TIMEOUT=60000   # 60 seconds

DEEPWIKI_REQUEST_TIMEOUT=120000  # 2 minutes for very large repos

```

### Raise Concurrency Limits

Increase `DEEPWIKI_MAX_CONCURRENCY` to allow more parallel requests, reducing total wall-clock time for large crawls. The default is 5; values between 15 and 20 often work well for high-bandwidth environments.

```bash
DEEPWIKI_MAX_CONCURRENCY=15

```

This modifies the `MAX_CONCURRENCY` constant used by `PQueue` in [`src/lib/httpCrawler.ts`](https://github.com/regenrek/deepwiki-mcp/blob/main/src/lib/httpCrawler.ts).

### Limit Crawl Depth for Large Repositories

When crawling extensive documentation sets, set `maxDepth` to `0` (root page only) or `1` (default) to minimize request volume. This is configured in the tool call parameters rather than environment variables.

```json
{
  "url": "https://deepwiki.com/large-org/large-repo",
  "maxDepth": 0,
  "mode": "pages"
}

```

### Inspect Error Arrays and Server Logs

After a crawl completes, check the `errors` array in the response to identify specific failing paths. Enable `verbose: true` in the request to see progress events including retry attempts and bytes transferred.

```typescript
if (result.errors?.length) {
  console.warn('Pages that failed to fetch:');
  for (const err of result.errors) {
    console.warn(`- ${err.path}: ${err.reason}`);
  }
}

```

### Validate Network Connectivity

Before assuming a configuration issue, verify direct access to the target domain from the server environment:

```bash
curl -I https://deepwiki.com/shadcn-ui/ui

```

If this fails, the issue lies with network access rather than deepwiki-mcp configuration.

## Configuration Examples

Complete working examples for common scenarios:

**Test Client Configuration:**

```typescript
import { McpTestClient } from './tests/McpClient.js'

async function run() {
  const client = new McpTestClient({
    cliEntryPoint: './bin/cli.mjs',
    env: {
      DEEPWIKI_REQUEST_TIMEOUT: '60000',   // 60s
      DEEPWIKI_MAX_CONCURRENCY: '12',
    },
  });

  await client.connectServer();
  try {
    const result = await client.callTool('deepwiki.fetch', {
      url: 'https://deepwiki.com/shadcn-ui/ui',
      maxDepth: 1,
      mode: 'pages',
      verbose: true,
    });
    console.log('Fetched pages:', result.content.length);
  } catch (e) {
    console.error('Tool call failed:', e);
  } finally {
    await client.close();
  }
}
run();

```

**Command Line Usage:**

```bash
DEEPWIKI_MAX_CONCURRENCY=20 DEEPWIKI_REQUEST_TIMEOUT=90000 npx mcp-deepwiki

```

**Inspecting Partial Failures:**

```typescript
// After a crawl with potential timeouts
const result = await client.callTool('deepwiki.fetch', {
  url: 'https://deepwiki.com/large/repo',
  maxDepth: 2,
  verbose: true,
});

if (result.errors && result.errors.length > 0) {
  console.error('Partial failure - some pages timed out:');
  result.errors.forEach((err: {path: string, reason: string}) => {
    console.error(`  ${err.path}: ${err.reason}`);
  });
}

```

## Summary

- **Schema validation errors** occur when request parameters fail `FetchRequest.safeParse` in [`src/schemas/deepwiki.ts`](https://github.com/regenrek/deepwiki-mcp/blob/main/src/schemas/deepwiki.ts), returning code `VALIDATION`.
- **Domain restrictions** enforce exact `deepwiki.com` hostnames in [`src/tools/deepwiki.ts`](https://github.com/regenrek/deepwiki-mcp/blob/main/src/tools/deepwiki.ts), rejecting other domains with `DOMAIN_NOT_ALLOWED`.
- **Network failures** are handled via retry logic in [`src/lib/httpCrawler.ts`](https://github.com/regenrek/deepwiki-mcp/blob/main/src/lib/httpCrawler.ts) with 3 attempts and 250ms exponential backoff, surfacing in the `errors` array.
- **Timeout errors** stem from Undici's default 30s limit and low default concurrency (5), resolvable by setting `DEEPWIKI_REQUEST_TIMEOUT` and `DEEPWIKI_MAX_CONCURRENCY`.
- **GitHub shortcut failures** originate in [`src/utils/resolveRepoFetch.ts`](https://github.com/regenrek/deepwiki-mcp/blob/main/src/utils/resolveRepoFetch.ts) when the Search API is rate-limited or unreachable.

## Frequently Asked Questions

### Why does my deepwiki-mcp request hang indefinitely?

Requests typically hang when the default Undici timeout (30 seconds) is exceeded during large repository crawls. The crawler in [`src/lib/httpCrawler.ts`](https://github.com/regenrek/deepwiki-mcp/blob/main/src/lib/httpCrawler.ts) processes pages with a concurrency limit controlled by `DEEPWIKI_MAX_CONCURRENCY` (default 5), and deep page trees generate many HTTP requests that accumulate beyond the timeout window. Set `DEEPWIKI_REQUEST_TIMEOUT=60000` or higher to allow sufficient time for completion.

### What is the difference between a validation error and a domain error in deepwiki-mcp?

A **validation error** (code `VALIDATION`) occurs when the JSON-RPC payload fails schema checks in [`src/schemas/deepwiki.ts`](https://github.com/regenrek/deepwiki-mcp/blob/main/src/schemas/deepwiki.ts), such as missing required fields or invalid types. A **domain error** (code `DOMAIN_NOT_ALLOWED`) occurs later in the pipeline at lines 96-103 of [`src/tools/deepwiki.ts`](https://github.com/regenrek/deepwiki-mcp/blob/main/src/tools/deepwiki.ts) when the URL hostname is not exactly `deepwiki.com`. Validation errors prevent execution, while domain errors indicate policy violations after parsing.

### How can I identify which specific pages failed during a crawl?

After a crawl completes, inspect the `errors` array in the response envelope. Each entry contains a `path` (the URL that failed) and a `reason` (the error message). This array is populated by the retry logic in [`src/lib/httpCrawler.ts`](https://github.com/regenrek/deepwiki-mcp/blob/main/src/lib/httpCrawler.ts) when all 3 retry attempts with exponential backoff are exhausted. Enable `verbose: true` in your request to see real-time progress and failure details in the server logs.

### Does increasing concurrency risk overwhelming the deepwiki.com servers?

The `DEEPWIKI_MAX_CONCURRENCY` setting controls the `PQueue` instance in [`src/lib/httpCrawler.ts`](https://github.com/regenrek/deepwiki-mcp/blob/main/src/lib/httpCrawler.ts), which limits simultaneous requests. While higher values (15-20) reduce crawl duration, the crawler respects [`robots.txt`](https://github.com/regenrek/deepwiki-mcp/blob/main/robots.txt) and filters non-HTML extensions by default. However, excessive concurrency may trigger rate-limiting from `deepwiki.com` or downstream network timeouts. Start with 10-12 and monitor for `errors` array entries indicating HTTP 429 or timeout failures.