Troubleshooting

Find solutions to common problems you may encounter while installing, configuring, or using the eBay MCP Server.

Can’t find your issue? Check the FAQ or report an issue on GitHub.

Quick Diagnosis

Use these questions to identify your issue category:

Installation Problems

Server won’t install or build fails

Authentication Errors

Credential validation or OAuth failures

MCP Client Issues

Client can’t find or connect to server

Runtime Errors

Server crashes or API calls fail

Installation Issues

Problems during installation or building the server.

Error: Node version too old

Problem: Your Node.js version is below 18.0.0Cause: The eBay MCP Server requires Node.js 18 or higher for modern JavaScript features and dependencies.Solution:

Update Node.js from nodejs.org
- Download the LTS (Long Term Support) version
- Run the installer
- Verify: node --version

Or use a version manager like nvm:

# Install nvm (macOS/Linux)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Install and use Node 18
nvm install 18
nvm use 18
nvm alias default 18

Verify installation:

node --version
# Should show v18.x.x or higher

After updating Node.js, you may need to reinstall the server: rm -rf node_modules && npm install

Error: npm install fails

Problem: Dependency installation fails with errorsCause: Common causes include corrupted cache, network issues, or permission problems.Solutions:Try 1: Clear npm cache

npm cache clean --force
npm install

Try 2: Delete node_modules and reinstall

rm -rf node_modules package-lock.json
npm install

Try 3: Check your internet connection

Verify you can access npmjs.org
Check if you’re behind a corporate firewall
Try using a different network

Try 4: Use a different registry (if in restricted network)

npm config set registry https://registry.npmjs.org/
npm install

If errors mention “EACCES” or “EPERM”, see the “Permission denied” section below.

Error: Permission denied

Problem: Insufficient permissions during installationCause: npm is trying to write to a directory you don’t have access to.Solutions:macOS/Linux:

# Fix ownership of the project directory
sudo chown -R $USER:$USER ebay-mcp-server
cd ebay-mcp-server
npm install

Windows:

Right-click PowerShell or Command Prompt
Select “Run as Administrator”
Navigate to the project directory
Run npm install

Alternative: Fix npm global permissions (macOS/Linux)

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.profile
source ~/.profile

Never use sudo npm install in the project directory - fix permissions instead.

Error: Build fails

Problem: TypeScript compilation errors during npm run buildCause: TypeScript compiler issues or source code errors.Solutions:Try 1: Ensure TypeScript is installed

npm install -g typescript
npm run build

Try 2: Clean and rebuild

# Remove build directory
rm -rf build/

# Rebuild
npm run build

Try 3: Check for version mismatches

# Reinstall all dependencies
rm -rf node_modules package-lock.json
npm install
npm run build

Try 4: Review build errors

Read the error output carefully
Look for specific file names and line numbers
Check if you’ve modified any source files

If you’ve modified source code, ensure your changes follow TypeScript syntax.

Error: Git clone fails

Problem: Cannot clone the repository from GitHubCause: Network connectivity, firewall restrictions, or Git configuration issues.Solutions:Try 1: Check internet connection

ping github.com

Try 2: Use HTTPS instead of SSH

git clone https://github.com/YosefHayim/ebay-mcp-server.git

Try 3: Configure Git proxy (if behind firewall)

git config --global http.proxy http://proxy.example.com:8080
git clone https://github.com/YosefHayim/ebay-mcp-server.git

Try 4: Download ZIP instead

Visit github.com/YosefHayim/ebay-mcp-server
Click “Code” → “Download ZIP”
Extract and use the files

If you download as ZIP, you won’t have Git history, but the code will work the same.

Tests failing during installation

Problem: npm test fails with errors after installationCause: Missing credentials, network issues, or environment configuration problems.Solution:

Configure your .env file before running tests:

cp .env.example .env
# Edit .env with your credentials

Check your internet connection:
- Tests require API connectivity to eBay
- Ensure you can reach api.ebay.com
Use Sandbox credentials for testing:
```
EBAY_ENVIRONMENT=sandbox
```

Run a single test to diagnose:

npm test -- --run getInventoryItems.test.ts

Skip tests during installation:
```
npm install --ignore-scripts
```

It’s normal for tests to fail if you haven’t configured credentials yet. Configure your .env file first.

Authentication Issues

Problems with eBay Developer credentials and OAuth.

Error: Invalid Client Credentials

Problem: Your Client ID or Client Secret is rejected by eBayCause: Incorrect credentials, typos, or using credentials from the wrong environment.Solution:

Verify credentials in eBay Developer Portal:
- Visit developer.ebay.com
- Navigate to My Account → Application Keys
- Confirm your Client ID (App ID) and Client Secret (Cert ID)
Check environment matching:
- Sandbox credentials only work with EBAY_ENVIRONMENT=sandbox
- Production credentials only work with EBAY_ENVIRONMENT=production
- Don’t mix environments!

Check for typos in .env:

# ❌ Wrong - has spaces
EBAY_CLIENT_ID = your_id

# ✅ Correct - no spaces around =
EBAY_CLIENT_ID=your_id

Ensure no quotes in .env:

# ❌ Wrong - has quotes
EBAY_CLIENT_ID="YourAppId"

# ✅ Correct - no quotes
EBAY_CLIENT_ID=YourAppId

Regenerate credentials if needed:
- In eBay Developer Portal, you can regenerate your Client Secret
- Update .env with the new secret immediately

Never share your Client Secret publicly or commit it to version control.

Error: Redirect URI Mismatch

Problem: OAuth flow fails with “redirect_uri_mismatch” errorCause: The redirect URI in your .env doesn’t match what’s configured in your eBay application.Solution:

Go to eBay Developer Portal:
- Visit developer.ebay.com
- Navigate to your application settings
Add the redirect URI:
- Find OAuth Redirect URIs section
- Click Add Redirect URI
- Enter: http://localhost:3000/callback
- Click Save

Update your .env file:

EBAY_REDIRECT_URI=http://localhost:3000/callback

Ensure exact match:
- URIs must match exactly including:
  - Protocol (http vs https)
  - Port number
  - Path
Try OAuth again:
```
npm run setup
```

You can have multiple redirect URIs configured in your eBay app. This is useful for different environments.

OAuth flow fails

Problem: OAuth authorization process doesn’t complete successfullyCause: Browser issues, popup blocking, or application configuration problems.Solutions:Common causes:

Browser blocking popups:
- Allow popups from the terminal/setup wizard
- Try manually copying the URL into your browser
Application not configured for OAuth:
- Verify OAuth is enabled in eBay Developer Portal
- Check that required scopes are granted:
  - sell.inventory
  - sell.marketing
  - sell.fulfillment
  - sell.analytics.readonly
  - sell.account
Redirect URI not configured:
- See “Redirect URI Mismatch” section above
Using wrong eBay account:
- Ensure you’re signing in with a seller account (for production)
- Sandbox works with any developer account

Manual OAuth flow:

# Generate OAuth URL
npm run generate-oauth-url

# Copy the URL and open in browser
# After authorization, copy the code from URL
# Exchange code for tokens
npm run exchange-oauth-code YOUR_CODE_HERE

The interactive setup wizard (npm run setup) handles OAuth automatically and is easier than manual flow.

Tokens expire immediately

Problem: User tokens show as expired right after generationCause: System clock is incorrect or token expiry timestamp is wrong format.Solution:

Check system time:
```
date
```
- Ensure your system clock is accurate
- Sync with time server if needed (macOS: System Preferences → Date & Time)

Check token expiry format in .env:

# ✅ Correct ISO 8601 format
EBAY_USER_TOKEN_EXPIRY=2024-12-31T23:59:59.000Z

# ❌ Wrong format
EBAY_USER_TOKEN_EXPIRY=12/31/2024

Regenerate tokens:
```
npm run setup
```
- The wizard will generate tokens with correct expiry
Verify token validity:
- User access tokens typically expire in 2 hours
- Refresh tokens expire in 18 months
- The server automatically refreshes expired access tokens

Token auto-refresh requires a valid refresh token. If both tokens are expired, run npm run setup again.

Configuration validation fails

Problem: npm run validate-config reports errorsCause: Missing or incorrectly formatted environment variables.Solution:Check these common issues:

Missing required variables:

# Required variables
EBAY_CLIENT_ID=...
EBAY_CLIENT_SECRET=...
EBAY_ENVIRONMENT=sandbox  # or production
EBAY_REDIRECT_URI=...

Extra spaces or quotes:

# ❌ Wrong
EBAY_CLIENT_ID = "your_id"

# ✅ Correct
EBAY_CLIENT_ID=your_id

Wrong environment value:

# ❌ Wrong - invalid value
EBAY_ENVIRONMENT=dev

# ✅ Correct - must be sandbox or production
EBAY_ENVIRONMENT=sandbox

Expired or invalid tokens:
- Remove expired tokens from .env
- Run npm run setup to regenerate

Re-run setup wizard:

npm run setup

The wizard validates each setting interactively and helps fix issues.

Start fresh by copying .env.example: cp .env.example .env

MCP Client Connection Issues

Problems connecting MCP clients (Claude Desktop, Cursor, etc.) to the server.

MCP client can't find the server

Problem: MCP client shows server as unavailable or can’t connectCause: Incorrect path in MCP client configuration or server not built.Solution:

Use absolute paths (not relative):

{
  "mcpServers": {
    "ebay": {
      "command": "node",
      "args": [
        "/Users/yourname/ebay-mcp-server/build/index.js"
      ]
    }
  }
}

Verify the path exists:

# Check that build/index.js exists
ls /absolute/path/to/ebay-mcp-server/build/index.js

Ensure server is built:
```
cd ebay-mcp-server
npm run build
```
Check config file location: Claude Desktop:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
- Linux: ~/.config/Claude/claude_desktop_config.json
Cursor:
- macOS: ~/Library/Application Support/Cursor/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json
- Windows: %APPDATA%\Cursor\User\globalStorage\rooveterinaryinc.roo-cline\settings\cline_mcp_settings.json
Restart your MCP client:
- Completely quit the application (Cmd+Q on Mac)
- Reopen and check for 🔨 tools icon

Tilde (~) expansion doesn’t work in JSON config files. Use full paths: /Users/yourname/...

Server starts but no tools appear

Problem: Server connects but tools don’t show up in MCP clientCause: Environment variables not passed to server or authentication failing silently.Solution:

Pass environment variables in config:

{
  "mcpServers": {
    "ebay": {
      "command": "node",
      "args": ["/absolute/path/to/ebay-mcp-server/build/index.js"],
      "env": {
        "EBAY_CLIENT_ID": "your_client_id",
        "EBAY_CLIENT_SECRET": "your_client_secret",
        "EBAY_ENVIRONMENT": "sandbox"
      }
    }
  }
}

Check server logs:
- Enable debug logging: "LOG_LEVEL": "debug" in env
- Check for authentication errors
- Verify 230+ tools are registered
Test server directly:
```
cd ebay-mcp-server
npm start
```
- Look for “230+ tools registered” message
- Check for any error messages
Verify credentials:
```
npm run validate-config
```

If only showing a few tools, client credentials mode may be active. Configure user tokens for full access.

Server crashes on startup

Problem: Server starts then immediately crashes or exitsCause: Missing dependencies, invalid configuration, or runtime errors.Solution:

Check server logs:
- Look for error messages before crash
- Common errors: missing environment variables, invalid credentials
Test server standalone:
```
cd ebay-mcp-server
node build/index.js
```
- This shows detailed error messages
Verify build is complete:
```
npm run build
ls build/index.js
```

Check Node.js version:

node --version
# Should be v18.0.0 or higher

Reinstall dependencies:

rm -rf node_modules package-lock.json
npm install
npm run build

Enable debug logging: Add to your MCP client config:

"env": {
  "LOG_LEVEL": "debug",
  "LOG_REQUESTS": "true"
}

Most startup crashes are due to missing or invalid environment variables. Double-check your .env file.

Tools appear but fail when used

Problem: Tools are available but return errors when calledCause: Authentication issues, rate limits, or invalid API requests.Solutions:Check authentication:

npm run validate-config

Common error patterns:

“Unauthorized” or “403 Forbidden”:
- Invalid credentials
- Expired tokens
- Wrong environment (sandbox vs production)
- Solution: Run npm run setup to reconfigure
“429 Too Many Requests”:
- Hit rate limit
- With client credentials: Upgrade to user tokens
- With user tokens: Wait 24 hours or upgrade eBay account
- See Rate Limit Issues section
“400 Bad Request”:
- Invalid parameters passed to tool
- Check tool documentation in API Reference
- Verify required fields are provided
“404 Not Found”:
- Resource doesn’t exist
- Wrong marketplace or environment
- Check that item/order/policy exists

Enable request logging to see detailed API calls: LOG_REQUESTS=true in your config

Runtime Issues

Problems that occur while the server is running.

Rate limit errors

Problem: “429 Too Many Requests” or rate limit exceeded errorsCause: You’ve exceeded your daily API request limit.Understanding Rate Limits:Client Credentials:

1,000 requests per day
Very limited for production use

User Tokens:

Basic seller: 10,000 requests/day
Business seller: 25,000 requests/day
Enterprise seller: 50,000 requests/day

Solutions:

Upgrade to user tokens (if using client credentials):

npm run setup
# Complete OAuth flow for user tokens

Monitor your usage:
- Track API calls in your application
- Implement request throttling
- Cache responses when possible
Optimize API calls:
- Use bulk operations when available
- Avoid unnecessary polling
- Batch related operations
Wait for limit reset:
- Rate limits reset every 24 hours
- Time-based limits reset by the second/minute
Upgrade eBay seller account:
- Higher tier accounts get higher limits
- Visit eBay Seller Hub for upgrade options

Repeatedly hitting rate limits may trigger additional restrictions on your API access.

Slow API responses

Problem: API calls take a long time to completeCause: Network latency, eBay Sell APIs performance, or inefficient queries.Solutions:

Check internet connection:
```
ping api.ebay.com
```
Use pagination for large datasets:
- Don’t request all items at once
- Use limit and offset parameters
- Process in smaller batches
Optimize queries:
- Request only needed fields
- Use filters to reduce response size
- Cache frequently accessed data
Check eBay Sell APIs status:
- Visit eBay Developer Status
- May be platform-wide performance issues
Consider geographic location:
- eBay Sell APIs may be slower from certain regions
- Consider using a proxy or VPN to different region

Some eBay Sell APIs endpoints are inherently slower than others, especially bulk operations and complex queries.

Unexpected API errors

Problem: Getting errors from eBay Sell APIs that aren’t related to authentication or rate limitsCause: Invalid requests, API changes, or data validation issues.Diagnostic steps:

Enable detailed logging:
```
LOG_LEVEL=debug
LOG_REQUESTS=true
```
Check error message details:
- Error code and message
- Which endpoint is failing
- Request parameters sent
Verify data format:
- Check required vs optional fields
- Validate data types (strings, numbers, dates)
- Ensure proper formatting (dates in ISO 8601, etc.)
Check API documentation:
- Visit eBay Developer Docs
- Verify endpoint requirements haven’t changed
- Check for known issues or deprecations
Test with minimal data:
- Try the simplest possible request
- Gradually add parameters to identify the issue
Environment mismatch:
- Ensure you’re using the right environment (sandbox vs production)
- Sandbox data doesn’t exist in production and vice versa

If you get consistent errors with a specific tool, check the API Reference for that tool’s documentation.

Memory leaks or high memory usage

Problem: Server memory usage grows over time or server runs out of memoryCause: Large response caching, memory leaks, or processing too much data at once.Solutions:

Restart the server periodically:
- Implement automatic restarts for long-running servers
- Monitor memory usage
Process data in chunks:
- Don’t load all items into memory
- Use streaming or pagination
- Process and discard data incrementally

Update to latest version:

cd ebay-mcp-server
git pull origin main
npm install
npm run build

Monitor memory usage:

# macOS/Linux
top -p $(pgrep -f ebay-mcp-server)

# Or use Node.js memory profiling
node --inspect build/index.js

Report persistent issues:
- If memory leaks persist, report an issue
- Include memory profiling data if possible

The MCP server is designed to be lightweight. Persistent memory issues may indicate a bug.

Token refresh failures

Problem: Server can’t automatically refresh expired access tokensCause: Invalid refresh token, network issues, or eBay Sell APIs issues.Solution:

Check refresh token in .env:

# Ensure refresh token is present and valid
EBAY_USER_REFRESH_TOKEN=v^1.1#i^1#...

Verify refresh token hasn’t expired:
- Refresh tokens last 18 months
- If expired, you’ll need to re-authorize
Re-run OAuth flow:
```
npm run setup
```
- This generates new access and refresh tokens
Check network connectivity:
```
ping api.ebay.com
```
Manual token refresh:
```
npm run refresh-token
```

The server automatically refreshes access tokens when they expire, as long as the refresh token is valid.

Environment-Specific Issues

Problems related to Sandbox vs Production environments.

Sandbox data doesn't appear in Production

Problem: Items or data created in Sandbox aren’t visible in ProductionCause: Sandbox and Production are completely separate environments.Understanding:

Sandbox: Isolated test environment with fake data
Production: Real eBay marketplace with real transactions

These environments:

Use different credentials
Have separate databases
Don’t share any data

Solution:You must recreate your data in Production:

Switch to Production:

EBAY_ENVIRONMENT=production
EBAY_CLIENT_ID=prod_client_id
EBAY_CLIENT_SECRET=prod_client_secret

Re-run OAuth for Production:
```
npm run setup
```
Recreate your listings/policies/data:
- Use the same tools in Production
- Test thoroughly in Sandbox first!

Production operations affect real listings and cost real money. Always test in Sandbox first.

Production credentials don't work

Problem: Production credentials fail validation or authorizationCause: Production requires additional setup and an active seller account.Requirements for Production:

Active eBay seller account
- Must have sold at least one item, or
- Completed seller registration
- Account in good standing
Production application approved
- Some APIs require eBay approval
- Check your application status in Developer Portal
Correct credentials:
- Production credentials are different from Sandbox
- Verify you’re using Production keys

Solution:

Verify seller account status:
- Visit eBay Seller Hub
- Ensure account is active and verified
Check application status:
- Visit eBay Developer Portal
- Verify Production application is approved
Use correct environment:
```
EBAY_ENVIRONMENT=production
```
Re-authorize with Production credentials:
```
npm run setup
```

Start with Sandbox for development. Only switch to Production when you’re ready for live operations.

Still Having Issues?

If your problem isn’t listed here:

FAQ

Check frequently asked questions

GitHub Issues

Search existing issues or create a new one

eBay Developer Support

Official eBay Sell APIs support resources

MCP Documentation

Model Context Protocol specification

Reporting Bugs

When reporting an issue, include:

Environment Information

- Node.js version: node --version
- npm version: npm --version
- Operating System: macOS/Windows/Linux
- MCP Client: Claude Desktop/Cursor/Other

Configuration

Environment: Sandbox or Production
Authentication mode: User tokens or Client credentials
Relevant .env variables (without secrets!)

Reproduction Steps

Step-by-step instructions to reproduce the issue
What you expected to happen
What actually happened

Logs and Errors

Complete error messages
Server logs (with LOG_LEVEL=debug)
Screenshots if applicable

Never include your Client Secret, access tokens, or refresh tokens in bug reports.

Getting Started

Authentication

Core Features

Guides

MCP Integration

Advanced

Support

Quick Diagnosis

Installation Problems

Authentication Errors

MCP Client Issues

Runtime Errors

Installation Issues

Authentication Issues

MCP Client Connection Issues

Runtime Issues

Environment-Specific Issues

Still Having Issues?

FAQ

GitHub Issues

eBay Developer Support

MCP Documentation

Reporting Bugs

Getting Started

Authentication

Core Features

Guides

MCP Integration

Advanced

Support

​Quick Diagnosis

Installation Problems

Authentication Errors

MCP Client Issues

Runtime Errors

​Installation Issues

​Authentication Issues

​MCP Client Connection Issues

​Runtime Issues

​Environment-Specific Issues

​Still Having Issues?

FAQ

GitHub Issues

eBay Developer Support

MCP Documentation

​Reporting Bugs

Quick Diagnosis

Installation Issues

Authentication Issues

MCP Client Connection Issues

Runtime Issues

Environment-Specific Issues

Still Having Issues?

Reporting Bugs