Troubleshooting

Common issues and solutions when using RailsPress.

Installation Issues

"ActionText not installed" Error

Symptom: Error about missing ActionText or has_rich_text undefined.

Solution: Install ActionText before RailsPress:

$ bin/rails action_text:install
$ bin/rails db:migrate

"ActiveStorage not configured" Error

Symptom: Header images fail to upload, or attachment-related errors.

Solution: Install and configure ActiveStorage:

$ bin/rails active_storage:install
$ bin/rails db:migrate

Configure a storage service in config/storage.yml and set it in your environment:

config.active_storage.service = :local

Rich Text Editor Not Loading

Symptom: Textarea appears instead of rich text editor; no formatting toolbar.

Solution: Ensure the editor JavaScript is loaded. Check your importmap:

pin "railspress", to: "railspress.js"

CSS Not Loading

Symptom: Admin interface appears unstyled or broken layout.

Solution: Include RailsPress stylesheets in your layout:

<%= stylesheet_link_tag "railspress/admin" %>

Authentication Issues

Admin is Publicly Accessible

Symptom: Anyone can access /railspress/admin without authentication.

Solution: RailsPress does not include authentication. Add it to your application:

class ApplicationController < ActionController::Base
  before_action :authenticate_user!, if: :railspress_admin?

  private

  def railspress_admin?
    request.path.start_with?("/railspress/admin")
  end
end

"current_user undefined" Error

Symptom: Error when enable_authors is set but current_user doesn't exist.

Solution: Set the correct author method for your authentication:

Railspress.configure do |config|
  config.enable_authors
  config.current_author_method = :current_admin  # Match your auth system
end

Entity Issues

Entity Not Appearing in Sidebar

Symptom: Registered entity doesn't show in admin navigation.

Solution: Ensure the entity is properly registered:

Railspress.configure do |config|
  config.register_entity :my_model
end

And the model includes the concern:

class MyModel < ApplicationRecord
  include Railspress::Entity

  railspress_fields :title, :description
end

Important: Restart the server after adding new entities.

"Entity not found" Error

Symptom: 404 or "entity not found" when accessing entity routes.

Causes and solutions:

• Entity not registered: Add to initializer
• URL uses wrong name: Use pluralized, underscored model name (team_members not TeamMember)
• Model missing concern: Add include Railspress::Entity

Fields Not Detected Correctly

Symptom: Wrong field type rendered in form (e.g., text input instead of rich text).

Solution: Use explicit type declaration:

railspress_fields :content, as: :rich_text
railspress_fields :published, as: :boolean
railspress_fields :tech_stack, as: :list

Changes to Model Not Reflected

Symptom: Updated railspress_fields not showing in forms.

Solutions:

• Save the model file
• Hard refresh the browser (not just Turbo navigation)
• Check Rails server logs for syntax errors
• Restart the server for array field changes

Import/Export Issues

Import Job Not Running

Symptom: Import stuck in "pending" status.

Solution: Ensure a background job processor is running:

# Sidekiq
$ bundle exec sidekiq

# Solid Queue (Rails 8+)
$ bin/rails solid_queue:start

Export Download Returns 404

Symptom: "Download" link doesn't work after export completes.

Causes:

• Export failed: Check the error_messages column
• ActiveStorage not configured: Ensure storage service is set
• File was cleaned up: Very old exports may have been purged

Display Issues

Reading Time Shows Wrong Value

Symptom: Reading time displays incorrect or zero minutes.

Solutions:

• Check words_per_minute configuration (default: 200)
• Ensure post has content (empty posts show 0 min)
• Re-save the post to recalculate cached reading time

Header Images Not Displaying

Symptom: Image field works but images don't show on frontend.

Solutions:

• Check if attached: @post.header_image.attached?
• Ensure feature is enabled: config.enable_header_images
• Configure ActiveStorage storage service properly

Rich Text Content Displays as Plain Text

Symptom: HTML tags visible instead of formatted content.

Solution: Use the content accessor directly (it returns ActionText HTML):

<%# Correct %>
<%= @post.content %>

<%# Wrong (escapes HTML) %>
<%= @post.content.to_plain_text %>

Debugging Tips

Debug Entity Configuration

config = Project.railspress_config
config.fields        # => { title: { type: :string }, ... }
config.label         # => "Projects"
config.route_key     # => "projects"

Check Registered Entities

Railspress.registered_entities  # => [:project, :testimonial]
Railspress.entity_for("projects")  # => EntityConfig instance

View Raw SQL

Railspress::Post.published.ordered.to_sql

Test Authentication

# Should redirect to login (if auth configured)
$ curl -I http://localhost:3000/railspress/admin

# Check response code
$ curl -s -o /dev/null -w "%{http_code}" http://localhost:3000/railspress/admin

Getting Help

1. Check this troubleshooting guide
2. Search existing GitHub issues
3. Review the documentation
4. Open a new issue with:
   • Rails version
   • RailsPress version
   • Error message and backtrace
   • Steps to reproduce