Troubleshooting Guide¶

Version: 1.0
Date: January 18, 2026
Status: Active

This guide helps diagnose and resolve common issues in Forma3D.Connect development and production environments.

Build Errors¶

"Cannot find module '@forma3d/...'"¶

Cause: Library not built or missing from node_modules.

Solution:

pnpm install
pnpm nx run-many --target=build --all

TypeScript Compilation Errors¶

Cause: Type mismatches or outdated generated types.

Solution:

# Regenerate Prisma types
pnpm prisma generate

# Clear Nx cache
pnpm nx reset

# Reinstall dependencies
rm -rf node_modules
pnpm install

ESLint Errors on Build¶

Cause: Code style violations.

Solution:

# Auto-fix linting issues
pnpm nx lint api --fix
pnpm nx lint web --fix

# Format code
pnpm format

"Cannot find module 'helmet'"¶

Cause: Dependency not installed.

Solution:

pnpm install

Runtime Errors¶

"ECONNREFUSED" to Database¶

Cause: Database not running or wrong connection string.

Solution:

# Check if PostgreSQL is running
docker ps | grep postgres
# or
pg_isready -h localhost -p 5432

# Verify DATABASE_URL in .env
cat .env | grep DATABASE_URL

# Start database if using Docker
docker start forma3d-postgres

# Test connection
psql $DATABASE_URL -c "SELECT 1"

"Invalid API key" from External Services¶

Cause: Missing or incorrect API credentials.

Solution: 1. Verify credentials in .env:

cat .env | grep -E "SHOPIFY|SIMPLYPRINT|SENDCLOUD"

"HMAC verification failed" for Webhooks¶

Cause: Webhook secret mismatch or payload modification.

Solution: 1. Verify SHOPIFY_WEBHOOK_SECRET matches Shopify settings 2. Ensure no proxy is modifying the webhook payload 3. Check raw body is available:

// main.ts should have rawBody: true
const app = await NestFactory.create(AppModule, { rawBody: true });

"Rate limit exceeded"¶

Cause: Too many requests in time window.

Solution:

# Check current rate limit settings
cat .env | grep RATE_LIMIT

# Increase limits for development
RATE_LIMIT_DEFAULT=10000
RATE_LIMIT_WEBHOOK=1000

# Or disable rate limiting temporarily
RATE_LIMIT_DISABLED=true

Webhook Issues¶

Shopify Webhooks Not Arriving¶

Investigation: 1. Check Shopify admin > Settings > Notifications > Webhooks 2. Look for failed webhook deliveries 3. Verify webhook URL is accessible from internet

Solution: 1. Use ngrok for local development:

ngrok http 3000
# Update webhook URL in Shopify to ngrok URL

SimplyPrint Webhooks Failing¶

Investigation: 1. Check SimplyPrint dashboard for webhook logs 2. Verify token configuration

Solution: 1. Verify SIMPLYPRINT_WEBHOOK_SECRET in .env 2. Check endpoint is reachable: curl https://your-domain/webhooks/simplyprint 3. Review API logs for verification failures

Duplicate Webhook Processing¶

Cause: Webhook idempotency not working.

Solution: 1. Check ProcessedWebhook table for entries 2. Verify cleanup job is running (hourly) 3. Check database connectivity

Performance Issues¶

Slow API Responses¶

Investigation:

# Check response times
curl -w "@curl-format.txt" -o /dev/null -s http://localhost:3000/api/v1/orders

# Enable Prisma query logging
DEBUG=prisma:query pnpm api:dev

Solution: 1. Add database indexes for slow queries 2. Implement pagination for large datasets 3. Add caching for frequently accessed data

High Memory Usage¶

Investigation:

# Check container memory
docker stats forma3d-api --no-stream

# Check Node.js heap
node --max-old-space-size=4096 # Increase heap if needed

Solution: 1. Look for memory leaks in code 2. Increase container memory limits 3. Optimize large object handling

Database Connection Pool Exhausted¶

Symptoms: - Slow queries - Connection timeouts - "Pool exhausted" errors

Solution:

# Increase pool size in DATABASE_URL
?connection_limit=20&pool_timeout=10

# Or via environment variables
DATABASE_POOL_SIZE=20
DATABASE_POOL_TIMEOUT_SECONDS=10

Testing Issues¶

Tests Timing Out¶

Cause: Async operations not completing.

Solution:

// Increase Jest timeout
jest.setTimeout(30000);

// Ensure all async operations complete
await app.close();

MSW Not Intercepting Requests¶

Cause: Handler not matching request URL or method.

Solution:

// Debug handlers
import { server } from './mocks/server';
server.listHandlers().forEach(handler => console.log(handler));

// Check URL patterns match
http.get('/api/v1/orders', ...) // Must match exact path

Database Tests Failing¶

Cause: Test database not available or dirty state.

Solution:

# Create test database
createdb forma3d_connect_test

# Run migrations on test database
DATABASE_URL=postgresql://...test pnpm prisma migrate deploy

# Clean up between tests
beforeEach(async () => {
  await prisma.order.deleteMany();
});

Coverage Threshold Not Met¶

Cause: Insufficient test coverage.

Solution: 1. Check coverage report: pnpm nx test api --coverage 2. Add tests for uncovered code 3. Or adjust thresholds in jest.config.cts (not recommended)

Deployment Issues¶

Docker Build Failing¶

Investigation:

# Build with verbose output
docker build --progress=plain -f apps/api/Dockerfile .

Common Fixes: 1. Ensure all dependencies are in package.json 2. Check Dockerfile uses correct base image 3. Verify build context includes all needed files

Container Not Starting¶

Investigation:

# Check container logs
docker logs forma3d-api

# Check container status
docker ps -a | grep forma3d

# Inspect container
docker inspect forma3d-api

Common Fixes: 1. Check all environment variables are set 2. Verify database is accessible from container 3. Check port bindings

TLS Certificate Issues¶

Investigation:

# Check certificate
echo | openssl s_client -connect your-domain:443 2>/dev/null | openssl x509 -noout -dates

# Check Traefik logs
docker logs forma3d-traefik | grep -i "cert\|acme\|error"

Common Fixes: 1. Ensure port 80 is open for ACME challenge 2. Check DNS points to correct IP 3. Verify Traefik configuration

Logs and Debugging¶

View API Logs¶

# Development
pnpm api:dev  # Logs appear in console with pino-pretty

# Docker
docker logs forma3d-api -f --tail 100

# Filter for errors
docker logs forma3d-api 2>&1 | grep -i error

# With timestamps
docker logs forma3d-api --timestamps

Enable Debug Mode¶

# Verbose logging
LOG_LEVEL=debug pnpm api:dev

# Prisma query logging
DEBUG=prisma:query pnpm api:dev

# All debug output
DEBUG=* pnpm api:dev

Check Sentry for Errors¶

1. Go to Sentry Dashboard
2. Select the Forma3D.Connect project
3. Filter by environment (development/staging/production)
4. Review error details and stack traces

Trace Requests with Correlation IDs¶

All requests include a x-correlation-id header. Use this to trace requests through logs:

# Find all logs for a specific request
docker logs forma3d-api 2>&1 | grep "abc-123-correlation-id"

Getting Help¶

1. Check this troubleshooting guide for common issues
2. Search existing Azure DevOps issues for similar problems
3. Review Sentry for error context and stack traces
4. Check the runbook for operational procedures
5. Ask in team chat with:
6. What you expected to happen
7. What actually happened
8. Steps to reproduce
9. Relevant error messages/logs

Revision History: