Common Issues & Solutions

This guide addresses the most frequently encountered issues when using MockForge and provides quick solutions.

Server Issues

Port Already in Use

Problem: Error: Address already in use (os error 98)

Solutions:

# Find what's using the port
lsof -i :3000
# On Windows: netstat -ano | findstr :3000

# Kill the process
kill -9 <PID>

# Or use a different port
mockforge serve --spec api.json --http-port 3001

Prevention: Check ports before starting:

# Quick check script
ports=(3000 3001 9080 50051)
for port in "${ports[@]}"; do
  if lsof -i :$port > /dev/null; then
    echo "Port $port is in use"
  fi
end

Server Won’t Start

Problem: MockForge exits immediately or fails silently

Debugging Steps:

Check configuration

# Validate config file
mockforge config validate --config mockforge.yaml

Check logs

# Enable verbose logging
RUST_LOG=debug mockforge serve --spec api.json 2>&1 | tee mockforge.log

Test with minimal config

# Start with just the spec
mockforge serve --spec examples/openapi-demo.json --http-port 3000

Check file permissions

ls -la api.json mockforge.yaml
chmod 644 api.json mockforge.yaml

Template & Data Issues

Template Variables Not Expanding

Problem: {{uuid}} appears literally in responses instead of generating UUIDs

Solutions:

# Enable template expansion via environment variable
MOCKFORGE_RESPONSE_TEMPLATE_EXPAND=true mockforge serve --spec api.json

# Or via config file
# mockforge.yaml
http:
  response_template_expand: true

# Or via CLI flag
mockforge serve --spec api.json --response-template-expand

Common Mistake: Forgetting that template expansion is opt-in for security reasons.

Faker Functions Not Working

Problem: {{faker.name}} not generating fake data

Solutions:

Enable template expansion (see above)
Check faker function name: Use lowercase, e.g., {{faker.name}} not {{Faker.Name}}
Install faker if required: Some advanced faker features may require additional setup

Valid faker functions:

{{faker.name}} - Person name
{{faker.email}} - Email address
{{faker.address}} - Street address
{{faker.phone}} - Phone number
{{faker.company}} - Company name

See Templating Reference for complete list.

Invalid Date/Timestamp Format

Problem: {{now}} generates invalid date format

Solutions:

# Use proper format in OpenAPI spec
properties:
  createdAt:
    type: string
    format: date-time  # Important!
    example: "{{now}}"

Alternative: Use custom format

{
  "timestamp": "{{now | date:'%Y-%m-%d'}}"
}

OpenAPI Spec Issues

Spec Not Loading

Problem: Error: Failed to parse OpenAPI specification

Solutions:

Validate spec syntax

# Using swagger-cli
swagger-cli validate api.json

# Or online
# https://editor.swagger.io/

Check file format

# JSON
cat api.json | jq .

# YAML
yamllint api.yaml

Check OpenAPI version

{
  "openapi": "3.0.3",  // Not "3.0" or "swagger": "2.0"
  ...
}

Resolve JSON schema references

# Use json-schema-ref-resolver if needed
npm install -g json-schema-ref-resolver
json-schema-ref-resolver api.json > resolved-api.json

404 for Valid Routes

Problem: Endpoints return 404 even though they exist in the spec

Debugging:

Check path matching

# Verify paths don't have trailing slashes mismatch
# Spec: /users (should match request: GET /users)
curl http://localhost:3000/users  # ✅
curl http://localhost:3000/users/ # ❌ May not match

Check HTTP method

# Ensure method matches spec
# Spec defines GET but you're using POST
curl -X GET http://localhost:3000/users  # ✅
curl -X POST http://localhost:3000/users # ❌ May not match

Enable debug logging

RUST_LOG=mockforge_http=debug mockforge serve --spec api.json

CORS Issues

CORS Errors in Browser

Problem: Access to fetch at 'http://localhost:3000/users' from origin 'http://localhost:3001' has been blocked by CORS policy

Solutions:

# mockforge.yaml
http:
  cors:
    enabled: true
    allowed_origins:
      - "http://localhost:3000"
      - "http://localhost:3001"
      - "http://localhost:5173"  # Vite default
    allowed_methods: ["GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS"]
    allowed_headers: ["Content-Type", "Authorization"]

Or via environment variable:

MOCKFORGE_CORS_ENABLED=true \
MOCKFORGE_CORS_ALLOWED_ORIGINS="http://localhost:3001,http://localhost:5173" \
mockforge serve --spec api.json

Debugging: Check browser console for exact CORS error message - it will tell you which header is missing.

Validation Issues

Valid Requests Getting Rejected

Problem: Requests return 422/400 even though they look correct

Solutions:

Check validation mode

# Use 'warn' instead of 'enforce' for development
MOCKFORGE_REQUEST_VALIDATION=warn mockforge serve --spec api.json

Check Content-Type header

# Ensure Content-Type matches spec
curl -X POST http://localhost:3000/users \
  -H "Content-Type: application/json" \
  -d '{"name": "John"}'

Check required fields

# Spec may require fields you're not sending
# Check spec for 'required' array

Validate request body structure

# Use Admin UI to see exact request received
# Visit http://localhost:9080 to inspect requests

Validation Too Strict

Problem: Validation rejects requests that should be valid

Solutions:

Temporarily disable validation

mockforge serve --spec api.json --validation off

Fix spec if it’s incorrect

// Spec might mark optional fields as required
"properties": {
  "name": { "type": "string" },
  "email": { "type": "string" }
},
"required": []  // Empty array = all optional

WebSocket Issues

Connection Refused

Problem: WebSocket connection fails immediately

Solutions:

Check WebSocket port

# Verify port is open
netstat -tlnp | grep :3001

Check replay file exists

# Ensure file path is correct
ls -la ws-replay.jsonl
MOCKFORGE_WS_REPLAY_FILE=./ws-replay.jsonl mockforge serve --ws-port 3001

Check WebSocket enabled

# Ensure WebSocket server is started
mockforge serve --ws-port 3001  # Explicit port needed

Messages Not Received

Problem: WebSocket connects but no messages arrive

Solutions:

Check replay file format

# Validate JSONL syntax
cat ws-replay.jsonl | jq -r '.'  # Should parse each line as JSON

Check message timing

// Replay file format
{"ts": 0, "dir": "out", "text": "Welcome"}
{"ts": 1000, "dir": "out", "text": "Next message"}

Check waitFor patterns

// Ensure regex patterns match
{"waitFor": "^CLIENT_READY$", "text": "Acknowledged"}

Configuration Issues

Config File Not Found

Problem: Error: Configuration file not found

Solutions:

Use absolute path

mockforge serve --config /full/path/to/mockforge.yaml

Check file name

# Valid names
mockforge.yaml
mockforge.yml
.mockforge.yaml
.mockforge.yml
mockforge.config.ts
mockforge.config.js

Check current directory

pwd
ls -la mockforge.yaml

Environment Variables Not Applied

Problem: Environment variables seem to be ignored

Solutions:

Check variable names

# Correct format: MOCKFORGE_<SECTION>_<OPTION>
MOCKFORGE_HTTP_PORT=3000       # ✅
MOCKFORGE_PORT=3000            # ❌ Wrong

Check shell reload

# Export and verify
export MOCKFORGE_HTTP_PORT=3000
echo $MOCKFORGE_HTTP_PORT  # Should show 3000

# Or use inline
MOCKFORGE_HTTP_PORT=3000 mockforge serve --spec api.json

Check precedence

# CLI flags override env vars
mockforge serve --spec api.json --http-port 3001
# Even if MOCKFORGE_HTTP_PORT=3000, port will be 3001

Performance Issues

Slow Response Times

Problem: API responses are slow

Solutions:

Disable template expansion if not needed

# Template expansion adds overhead
mockforge serve --spec api.json  # No templates = faster

Reduce validation overhead

# Validation adds latency
mockforge serve --spec api.json --validation warn  # Faster than 'enforce'

Check response complexity

# Large responses or complex templates slow things down
# Consider simplifying responses for development

Monitor resource usage

# Check CPU/memory
top -p $(pgrep mockforge)

High Memory Usage

Problem: MockForge consumes too much memory

Solutions:

Limit connection pool

MOCKFORGE_MAX_CONNECTIONS=100 mockforge serve --spec api.json

Disable features not needed

# Minimal configuration
mockforge serve --spec api.json \
  --validation off \
  --response-template-expand false \
  --admin false

Check for memory leaks

# Monitor over time
watch -n 1 'ps aux | grep mockforge | grep -v grep'

Docker Issues

Container Exits Immediately

Problem: Docker container starts then immediately stops

Solutions:

Check logs

docker logs <container-id>
docker logs -f <container-id>  # Follow logs

Run interactively

docker run -it --rm mockforge mockforge serve --spec api.json

Check volume mounts

# Ensure spec file is accessible
docker run -v $(pwd)/api.json:/app/api.json \
  mockforge mockforge serve --spec /app/api.json

Port Mapping Issues

Problem: Can’t access MockForge from host

Solutions:

# Proper port mapping
docker run -p 3000:3000 -p 9080:9080 mockforge

# Verify ports are exposed
docker port <container-id>

Permission Issues

Problem: Can’t read/write mounted volumes

Solutions:

# Fix permissions
sudo chown -R 1000:1000 ./fixtures ./logs

# Or run as specific user
docker run --user $(id -u):$(id -g) \
  -v $(pwd)/fixtures:/app/fixtures \
  mockforge

Admin UI Issues

Admin UI Not Loading

Problem: Can’t access http://localhost:9080

Solutions:

Enable admin UI

mockforge serve --spec api.json --admin --admin-port 9080

Check port

# Verify port is listening
curl http://localhost:9080
netstat -tlnp | grep :9080

Try different port

mockforge serve --spec api.json --admin --admin-port 9090
# Access at http://localhost:9090

Admin API Not Working

Problem: Admin UI loads but API calls fail

Solutions:

# Test admin API directly
curl http://localhost:9080/__mockforge/status

# Enable admin API explicitly
mockforge serve --spec api.json --admin --admin-api-enabled

Plugin Issues

Plugin Won’t Load

Problem: Error: Failed to load plugin

Solutions:

Check plugin format

# Validate WASM file
file plugin.wasm  # Should show: WebAssembly

# Check plugin manifest
mockforge plugin validate plugin.wasm

Check permissions

# Ensure plugin file is readable
chmod 644 plugin.wasm

Check compatibility

# Plugin may be for different MockForge version
mockforge --version
# Check plugin requirements

Plugin Crashes

Problem: Plugin causes MockForge to crash

Solutions:

Check plugin logs

RUST_LOG=mockforge_plugin=debug mockforge serve --plugin ./plugin.wasm

Check resource limits

# plugin.yaml
capabilities:
  resources:
    max_memory_bytes: 67108864  # 64MB
    max_cpu_time_ms: 5000      # 5 seconds

Getting More Help

If none of these solutions work:

Collect debug information

# System info
uname -a
rustc --version
mockforge --version

# Check logs
RUST_LOG=debug mockforge serve --spec api.json 2>&1 | tee debug.log

# Test with minimal config
mockforge serve --spec examples/openapi-demo.json --http-port 3000

Search existing issues
- Check GitHub Issues
- Search for similar problems
Create minimal reproduction
- Create smallest possible config that reproduces issue
- Include OpenAPI spec (if relevant)
- Include error logs
Open GitHub issue
- Use descriptive title
- Include system info, version, logs
- Attach minimal reproduction

See Also:

Troubleshooting Guide - Detailed diagnostic steps
FAQ - Common questions and answers
Configuration Reference - All configuration options

MockForge Documentation