Skip to main content

​
Troubleshooting Guide

Solutions to common problems when using the FRED MCP Server.

​
Authentication Issues

​
API Key Not Found

Symptoms: “Bad Request. The value for variable api_key is not registered.” Solutions:
1

Verify API Key

Check that your API key is exactly 32 characters
2

Check Environment Variable

Ensure FRED_API_KEY is set correctly
3

Restart Server

Restart the MCP server after config changes
4

Test Key

Try the key directly in a browser:
https://api.stlouisfed.org/fred/series?series_id=GDP&api_key=YOUR_KEY

​
Rate Limiting

​
Too Many Requests (429)

Symptoms: “Too many requests” error Solutions:
  • Wait 60 seconds before retrying
  • Reduce request frequency
  • Use date ranges to limit data
  • Plan queries to avoid redundant requests

​
Data Issues

​
Series Not Found (404)

Symptoms: “Bad Request. The series does not exist.” Solutions:
  • Verify series ID spelling
  • Check if series has been discontinued
  • Search for alternative series
  • Use fred_search to find correct ID

​
Empty Results

Symptoms: No data returned Solutions:
  • Check date range is valid
  • Verify series has data for requested period
  • Try broader date range
  • Check if series is vintage/discontinued

​
Connection Issues

​
Server Won’t Start

Symptoms: MCP server fails to launch Solutions:
Ensure Node.js v16+ is installed:
node --version

npm uninstall -g fred-mcp-server
npm install -g fred-mcp-server
Ensure execute permissions:
chmod +x $(which fred-mcp-server)
Check error messages in console output

​
Performance Issues

​
Slow Requests

Symptoms: Requests take too long Solutions:
  • Limit date ranges
  • Reduce result limits
  • Use specific series IDs
  • Plan queries to minimize API calls

​
Getting Help

GitHub Issues

Report bugs and request features

FRED API Docs

Official FRED API documentation

FAQ

Frequently asked questions

Configuration

Setup guide