Diagnosing Turbo Disabled or Inactive in Rails Applications

When Turbo mode reports disabled or the banner is missing from the UI despite being enabled in configuration, engineers often assume a feature flag issue. The useful takeaway: verify the Turbo flag in the correct environment context and confirm the application reloads the setting before investigating deeper causes.

Recognizable conditions that trigger Turbo diagnostics

• Turbo appears disabled despite configuration: Logs report Turbo disabled or the Turbo banner is absent in the UI.
• Performance gains are negligible or absent: Request latency remains unchanged after enabling Turbo, or throughput does not increase.
• Runtime errors or timeouts when Turbo is active: Stack traces show failures in Turbo middleware or cache invalidation.
• Inconsistent behavior across environments: Turbo works in staging but not in production, indicating environment-specific configuration or resource limits.
• Resource exhaustion: CPU or memory spikes when Turbo is enabled, suggesting Turbo's optimization pipeline is overloading the system.

Diagnostic table: condition → likely cause

Ordered checks to isolate the root cause

1. Confirm the Turbo flag is set in the environment configuration and reload the application. Check log entries or UI indicators. Where to run: RAILS_ROOT or the project root. Required permissions: read access to config files and ability to restart the app. Expected check: Log line confirming Turbo enabled, or UI banner present. Risk: Reloading may temporarily interrupt requests if the app stops gracefully.
2. Measure baseline request latency and throughput without Turbo. Then enable Turbo and remeasure to confirm any change. Where to run: application performance monitoring (APM) tool, or manual curl/benchmark script. Required permissions: read access to metrics; write may be needed to toggle the flag. Expected check: Latency difference of at least 10–20 % if Turbo is functioning. Risk: Benchmark scripts should run in a non-production environment or during low-traffic windows.
3. Inspect application logs for errors or stack traces that occur only when Turbo is active. Where to run: Log files (e.g., log/production.log) or centralized logging platform. Required permissions: read access to logs. Expected check: Absence of Turbo-related stack traces when Turbo is off; presence of specific errors when on. Risk: Logs may be rotated or truncated; ensure sufficient retention.
4. Check system metrics (CPU, memory, cache hit rates) before and after enabling Turbo to identify resource contention. Where to run: System monitoring (e.g., top, htop, cloud provider metrics). Required permissions: read-only access to monitoring dashboards or CLI tools. Expected check: CPU/memory increase should stay within baseline thresholds (e.g., < 15 % spike). Risk: Monitoring tools may add slight overhead; account for that in thresholds.

Fixes tied to each finding

• Feature flag not reloaded: After changing the Turbo configuration flag, restart the application server or trigger a code reload. In Rails, this typically means rails restart or sending a SIGUSR2 to the Puma process.
• Turbo middleware not in pipeline: Verify that the Turbo middleware is placed early in the Rack stack, before any static file serving or cache middleware that might bypass it. In a typical Rails application.rb or config/routes.rb, ensure the Turbo engine is mounted or its middleware is added.
• Conflicting gems or stale assets: Run bundle update to resolve gem version conflicts. Clear the asset cache with rails assets:clean or delete compiled Turbo JavaScript packs and rebuild with rails assets:precompile.
• Environment mismatch: Confirm that the Turbo flag and associated configuration are set for the correct RAILS_ENV. Double-check config/environments/production.rb for any overrides that disable Turbo.
• Resource exhaustion: If Turbo precompilation or optimization runs on every request, consider moving it to a background job or enabling caching. Adjust worker process counts or increase allocated memory for the application server.

Escalation criteria

If none of the ordered checks resolve the issue, gather the following before escalating:

• Full application logs from the period when Turbo was active, including any stack traces.
• System resource graphs (CPU, memory, I/O, network) spanning the time Turbo was enabled and disabled.
• Configuration diff between environments where Turbo works and where it does not.
• Version information for the framework, Turbo gem, and Ruby/Runtime.

Provide this data to the framework maintainers or platform operations team. If the issue appears to be a bug in the Turbo middleware itself, include a minimal reproduction case and the exact environment details.

Concrete example: enabling Turbo and verifying it takes effect

Assume a Rails 7.1 application with Hotwire Turbo. The configuration flag is config.turbo.enabled = true in config/initializers/turbo.rb.

# In config/initializers/turbo.rb
Rails.application.config.turbo.enabled = true

After adding or modifying this file, reload the application:

# From the project root, with appropriate permissions
rails restart
# or, for Puma:
pumactl -S config/puma.rb restart

Check logs for:

Turbo enabled in production environment

If the line does not appear, verify that the initializer is being loaded in the correct environment and that no other configuration is overriding it.

Limitations and how to verify the result

This guide assumes Turbo is enabled via a standard configuration flag; custom implementations or heavily modified pipelines may differ. Issues can be compounded by other performance-tuning features such as HTTP cache layers, CDNs, or load balancers that interact with Turbo's request path. The diagnostic steps rely on visibility into application logs and metrics; without instrumentation, verification may be inconclusive.

To practically check the result: after applying a fix, remeasure request latency and throughput as described in the ordered checks. A successful fix should show at least a single-digit percent improvement in latency or a measurable increase in request throughput. If no change is observed, revisit the diagnostic table and ensure the Turbo flag is active in the exact environment where the measurements are taken.