1. Routing Not Working

Understanding the Issue

Hanami routes are not being recognized, or unexpected responses occur when navigating the application.

Root Causes

• Incorrect route definitions in config/routes.rb.
• Missing or improperly configured actions in controllers.
• Namespace conflicts affecting route resolution.

Fix

Ensure that routes are correctly defined:

# config/routes.rb
root to: "home#index"
get "/users", to: "users#index"
post "/users", to: "users#create"

Check available routes with:

bundle exec hanami routes

Ensure the controller action exists and is properly named:

module Web
  module Controllers
    module Users
      class Index
        include Web::Action
        def call(params)
          self.body = "User list"
        end
      end
    end
  end
end

2. Database Connection Issues

Understanding the Issue

Hanami cannot connect to the database, or database migrations fail.

Root Causes

• Incorrect database configuration in config/database.yml.
• Missing database adapter dependencies.
• Database service is not running.

Fix

Verify the database configuration:

# config/database.yml
development:
  adapter: "postgresql"
  database: "hanami_development"
  host: "localhost"
  user: "user"
  password: "password"

Ensure the database service is running:

sudo systemctl start postgresql

Run pending migrations:

bundle exec hanami db migrate

3. View Rendering Issues

Understanding the Issue

Hanami views fail to render properly, or templates are not being applied.

Root Causes

• Incorrect view file structure.
• Template file missing or misnamed.
• Improper variable passing to views.

Fix

Ensure views are in the correct location:

# apps/web/templates/home/index.html.erb
<h1>Welcome to Hanami</h1>

Ensure the controller passes data correctly:

module Web
  module Views
    module Home
      class Index
        include Web::View
      end
    end
  end
end

Check for missing or incorrectly named templates.

4. Configuration Conflicts

Understanding the Issue

Unexpected behavior due to incorrect Hanami environment configurations.

Root Causes

• Misconfigured config/environment.rb.
• Conflicting settings between environments (development, test, production).
• Outdated application dependencies.

Fix

Verify environment configurations:

HANAMI_ENV=development bundle exec hanami server

Ensure dependencies are up to date:

bundle update

Check for environment-specific settings in config/environment.rb.

5. Performance Bottlenecks

Understanding the Issue

Hanami application runs slower than expected, impacting response times.

Root Causes

• Unoptimized database queries.
• Excessive rendering overhead.
• Blocking I/O operations affecting performance.

Fix

Optimize database queries using indexes:

CREATE INDEX users_email_idx ON users (email);

Use caching mechanisms where applicable:

require "hanami/cache"
cache = Hanami::Cache.new
cache.fetch("user:1") { UserRepository.new.find(1) }

Optimize rendering by reducing unnecessary computations in views.

Conclusion

Hanami is a powerful Ruby framework, but troubleshooting routing errors, database connection problems, view rendering issues, configuration conflicts, and performance bottlenecks is essential for building scalable applications. By following best practices for configuration, query optimization, and debugging, developers can ensure efficient Hanami development.

FAQs

1. Why is my Hanami route not working?

Check that routes are correctly defined in config/routes.rb and verify them using bundle exec hanami routes.

2. How do I fix Hanami database connection errors?

Ensure the database service is running, check config/database.yml settings, and verify installed database adapters.

3. Why is my Hanami view not rendering?

Ensure the template file exists in the correct directory and that controller actions pass required variables to views.

4. How can I improve Hanami performance?

Optimize database queries, use caching, and avoid unnecessary computations in views.

5. How do I debug configuration issues in Hanami?

Run HANAMI_ENV=development bundle exec hanami server and check environment-specific settings in config/environment.rb.