Stoplight Platform Technical Reference

Critical Configuration Requirements

Production-Ready Settings

• Memory allocation: Node.js containers require minimum 1GB RAM, default 512MB causes OOMKiller termination
• File size limits: Individual files max 5MB, total project max 50MB, over 500 endpoints cause build timeouts
• Schema depth: Maximum 10 levels deep before platform failures
• Repository structure: OpenAPI files must be in root directory or explicit paths configured

Authentication Configuration

# Corporate environments require certificate management
NODE_TLS_REJECT_UNAUTHORIZED=0  # Development only
# Production: Add corporate CA certificates to system store

Common Failure Modes and Solutions

Studio Application Failures

Blank White Screen on Startup

• Cause: Display driver conflicts, especially Windows + WSL2
• Impact: Complete application unusability
• Solution: Update display drivers, restart with hardware acceleration disabled

Memory Leaks with Large Specifications

• Threshold: Files over 5MB or deeply nested schemas
• Symptoms: Progressive slowdown, eventual crash
• Since: Version 2.9.0 (unresolved by SmartBear)
• Workaround: Split specifications into smaller files using $ref

Duplicate Stable IDs Error

• Trigger: Copy-paste operations, file renames without reference updates
• Resolution Time: 30 minutes (experienced) to 3 hours (first-time)
• Nuclear Fix:
  1. Export project data
  2. Delete problematic files
  3. Clear browser cache for *.stoplight.io
  4. Re-upload from scratch
  5. Reconfigure custom domains

Git Integration Breakages

YAML Merge Conflict Resolution

• Problem Severity: 90 minutes of manual diff resolution for simultaneous edits
• Root Cause: Git's default merge algorithm doesn't understand YAML structure
• Prevention Strategy:
  • Assign single-person spec file ownership
  • Use $ref for collaborative changes
  • Configure .gitattributes with custom merge drivers

# Install semantic merge tools
brew install yq  # macOS
sudo apt-get install yq  # Ubuntu

# Merge YAML with conflict resolution
yq eval-all 'select(fileIndex == 0) * select(fileIndex == 1)' base.yaml branch.yaml

Branch Sync Failures

• Common Triggers: Force pushes, branch renames, rebase operations
• Detection: Check status.stoplight.io first (platform downtime frequent)
• Debug Process:
  1. Verify webhook delivery in Git provider
  2. Force manual sync (rate-limited)
  3. Nuclear reset: disconnect/reconnect Git integration (5-minute cache delay)

Permission Denied Authentication

• Frequency: GitHub tokens expire after 1 year
• Enterprise Issues: SAML/SSO service accounts need special exemptions
• Network Cause: Corporate firewalls blocking *.stoplight.io domains

Mock Server Production Issues

Memory Consumption Problems

• Symptoms: Progressive slowdown, null responses, container termination
• Resource Requirements: 1GB RAM minimum, 2GB recommended for large specs
• Mitigation: Restart containers every few hours in CI/CD

FROM stoplight/prism:4
ENV NODE_OPTIONS="--max-old-space-size=2048"
COPY your-spec.yaml .
EXPOSE 4010
CMD ["mock", "-h", "0.0.0.0", "your-spec.yaml"]

404 Errors for Valid Endpoints

• Primary Cause: Incorrect servers configuration
• Secondary Cause: Proxy misconfiguration
• Debug Method: Use --verbose flag to trace example selection

Authentication Header Issues

• Reality: Mock servers don't validate auth, only return defined responses
• Common Problem: Headers not passed through proxy correctly
• Solution: Define explicit header examples in responses

Platform Performance Degradation

Documentation Publishing Failures

• Silent Failure Risk: Platform shows stale sync timestamps while serving outdated content
• Detection Strategy: Monitor Git commits vs published doc timestamps
• Impact: Users receive incorrect API information

Component Library Beta Instability

• Status: Beta for 2+ years with regular breakages
• Failure Types: Random unavailability, broken references, circular dependencies, version conflicts
• Recommendation: Avoid for production; use Git submodules instead

Enterprise SSO Issues

• Authentication Loops: Infinite redirects require cookie/cache clearing
• Session Duration: 1 hour instead of documented 8 hours
• Permission Resets: Admin permissions randomly reset monthly

Resource Requirements and Constraints

Time Investments

• YAML merge conflict resolution: 90 minutes for complex conflicts
• Git integration reset: 30 minutes (experienced) to 3 hours (troubleshooting)
• Component library migration: Avoid - use Git submodules (30% less maintenance)
• Platform sync monitoring: Set up automated checks to prevent 2-hour debugging sessions

Expertise Prerequisites

• YAML semantic understanding: Required for merge conflict resolution
• Docker memory management: Essential for production mock servers
• Corporate networking knowledge: Needed for enterprise deployments
• Git workflow expertise: Critical for avoiding integration disasters

Infrastructure Limits

• Concurrent mock requests: Performance degrades with high volume
• Build timeout threshold: Large specs (>10MB) fail without error messages
• Webhook rate limits: Too many manual syncs temporarily block projects
• CDN cache delays: 5-minute delay for configuration changes

Critical Warnings and Breaking Points

Undocumented Limitations

• File path depth: Auto-discovery fails with nested directory structures
• Multipart form data: Limited mock server support for file uploads
• External reference resolution: Spectral fails with complex $ref chains
• Memory leaks: Progressive degradation in long-running containers

Production Failure Scenarios

• Platform sync failure: Users see outdated API documentation
• Mock server OOM: Integration tests fail randomly in CI/CD
• Component library corruption: Shared schemas become unavailable across organization
• SSL certificate issues: Corporate firewalls block platform access

Data Loss Risks

• Git integration reset: Loses some project history but fixes 90% of sync issues
• Component library dependency: Breaking changes affect multiple projects simultaneously
• Manual file deletion: Required for stable ID conflicts, risks content loss

Alternative Tools and Fallbacks

When Stoplight Fails

• Studio crashes: Use Swagger Editor (editor.swagger.io) as immediate fallback
• Platform unavailable: Use Redoc for local documentation generation
• Mock server issues: Switch to Insomnia or Postman for API testing
• Git integration broken: Use VS Code OpenAPI extensions for local editing

Monitoring and Detection Tools

• Platform status: status.stoplight.io (check before debugging)
• Documentation uptime: Uptime Robot or Pingdom for published URLs
• Memory usage: Docker stats for container resource monitoring
• Webhook delivery: GitHub/GitLab webhook logs for integration issues

Migration Considerations

• Component libraries: Migrate to Git submodules before production use
• Large specifications: Split into smaller files before hitting size limits
• Enterprise authentication: Plan for frequent re-authentication cycles
• Build monitoring: Implement external build status tracking (platform provides none)

Emergency Procedures

Immediate Response Actions

1. Check status.stoplight.io - Platform outages more common than admitted
2. Clear browser cache - Fixes 60% of UI issues
3. Restart mock containers - Resolves memory-related failures
4. Force Git sync - Manual trigger when automatic sync fails
5. Nuclear reset Git integration - Last resort for persistent sync issues

Prevention Strategies

• Assign spec file ownership - Prevents YAML merge conflicts
• Monitor resource usage - Prevent container OOM kills
• Backup component definitions - Local copies of shared schemas
• Automate sync monitoring - Detect stale documentation automatically
• Stage component changes - Test in non-production environment first

This technical reference provides the operational intelligence needed for successful Stoplight implementation while avoiding the documented pitfalls that cause production failures.