---
title: Common Fixes
description: Common issues and solutions for Docfork MCP.
---
import { Callout } from "fumadocs-ui/components/callout";
## Quick Checklist
Before diving into specific issues, verify these basics:
- Confirm Node.js v18+ is installed (`node --version`)
- Update to the latest Docfork MCP package (`docfork@latest`)
- Verify connectivity with `curl https://mcp.docfork.com/mcp/ping`
- Add your API key to the configuration if you hit rate limits
<Callout title="Skip Node.js issues entirely" type="info">
Use the remote server connection instead of local npx. Most MCP clients support connecting to
`https://mcp.docfork.com/mcp` directly, which requires no local Node.js installation. See [All MCP
Clients](/integrations/overview) for configuration examples.
</Callout>
## Common Fixes
### Use Latest Version
Add `@latest` to ensure you're using the most recent version:
```json
{
"mcpServers": {
"docfork": {
"command": "npx",
"args": ["-y", "docfork@latest"]
}
}
}
```
### Module Not Found / Use Alternative Runtimes
If you encounter `ERR_MODULE_NOT_FOUND`, try `bunx` or `deno` instead of `npx`:
**Using Bun:**
```json
{
"mcpServers": {
"docfork": {
"command": "bunx",
"args": ["-y", "docfork"]
}
}
}
```
**Using Deno:**
```json
{
"mcpServers": {
"docfork": {
"command": "deno",
"args": ["run", "--allow-env", "--allow-net", "npm:docfork"]
}
}
}
```
This often resolves module resolution issues in environments where `npx` doesn't properly install or resolve packages.
### ESM Resolution Issues
For errors like `Error: Cannot find module 'uriTemplate.js'`, try the `--experimental-vm-modules` flag:
```json
{
"mcpServers": {
"docfork": {
"command": "npx",
"args": ["-y", "--node-options=--experimental-vm-modules", "docfork"]
}
}
}
```
### TLS/Certificate Issues
Use the `--experimental-fetch` flag to bypass TLS-related problems:
```json
{
"mcpServers": {
"docfork": {
"command": "npx",
"args": ["-y", "--node-options=--experimental-fetch", "docfork"]
}
}
}
```
### Port Already In Use (EADDRINUSE)
If you see an error like `Error: listen EADDRINUSE: address already in use :::3000`, this means you have `MCP_TRANSPORT=streamable-http` configured:
**Option 1: Use default stdio transport (recommended)**
Remove the `MCP_TRANSPORT` environment variable to use the default stdio transport, which avoids port conflicts:
```json
{
"mcpServers": {
"docfork": {
"command": "npx",
"args": ["-y", "docfork"]
}
}
}
```
**Option 2: Automatic port allocation**
<Callout title="Tip" type="info">
The server automatically finds an available port if the default port is in use. You'll see a
message like: ``` Port 3000 is already in use, using port 3001 instead ```
</Callout>
**Option 3: Configure a custom port**
```json
{
"mcpServers": {
"docfork": {
"command": "npx",
"args": ["-y", "docfork"],
"env": {
"MCP_TRANSPORT": "streamable-http",
"PORT": "3500"
}
}
}
}
```
### Node.js Version
Ensure you're using Node.js v18 or higher for native fetch support. Check your version:
```bash
node --version
```
If you're on an older version, update Node.js from [nodejs.org](https://nodejs.org/) or use a version manager like `nvm`.
### `Invalid API Key` or `401 Unauthorized`
**Cause:** Your API key is missing, incorrect, or expired.
**Solution:**
1. Log in to [app.docfork.com](https://app.docfork.com) and generate a new key.
2. Ensure you are passing it in the `headers` (Remote) or `--api-key` argument (Local).
3. If using Cursor, restart the editor to ensure new settings are loaded.
### Latency is high (> 2s)
**Cause:** This usually happens when using a **Local** installation (`npx docfork`) on a slow internet connection, as the code must be downloaded and executed locally.
**Solution:**
Switch to the **Remote** connection (`https://mcp.docfork.com/mcp`). This offloads the processing to our cloud servers, which are optimized for sub-second retrieval.
<Callout title="Still stuck?" type="error">
If you can't resolve the issue, contact us at [support@docfork.com](mailto:support@docfork.com) or
raise a [GitHub issue](https://github.com/docfork/docs/issues).
</Callout>
