---
title: A hands-on tutorial to debugging your code with pry-byebug
description: Like most new developers, I started as a puts developer. Then, I discovered
  pry-byebug and debugging things got a lot easier. This is a beginner-level, hands-on,
  introduction to debbuging your code with pry-byebug. Behold the power of binding.pry!
author:
  name: Rémi Mercier
  url: https://remimercier.com/about/
canonical_url: https://remimercier.com/pry-byebug-tutorial/
published: '2020-04-07'
language: en
topics:
- Debugging
site:
  name: Rémi Mercier
  url: https://remimercier.com
---

# A hands-on tutorial to debugging your code with pry-byebug

> Like most new developers, I started as a puts developer. Then, I discovered pry-byebug and debugging things got a lot easier. This is a beginner-level, hands-on, introduction to debbuging your code with pry-byebug. Behold the power of binding.pry!

Published on 2020-04-07 by Rémi Mercier.
Original: https://remimercier.com/pry-byebug-tutorial/

Like most new developers, I first started as a `puts` debugger. I would write `puts` everywhere to see what's what.

Debugging is hard enough, so knowing your tools makes that task much simpler. When I learned the ropes of _[pry-byebug](https://github.com/deivid-rodriguez/pry-byebug){:target="\_blank"}_, I decided to passed that knowledge along to anyone who'd hear it!

Let's dive right in, so I can give you practical tips on using _pry-byebug_ in your [Rails applications](/topics/rails/).

## Set up pry-byebug

Add the gem to your gemfile.

```ruby
  gem 'pry-byebug'
```

Then run:

```zsh
  bundle install
```

That's it.

## Some context

Before we begin, let's build up a bit of context, so my demo is more idiomatic. I'll draw on something that happened to me a while back.

Here's our scenario:
- Some third-party service periodically sends us a webhook with people's information.
- We receive and handle the data: checking for people in our database, creating them if need be, etc.
- We check that people were either matched to an existing instance or created.

Sounds good? Let's check our code now.

First, here's an excerpt from the data **we expect** to receive:

```json
  {
    people: [
      { first_name: 'Buffy', last_name: 'Summers', email: 'buffy@sunnydale.edu'},
      { first_name: 'Willow', last_name: 'Rosenberg', email: 'willow@gmail.com'},
      { first_name: 'Rupert', last_name: 'Giles', email: 'giles@sunnydale.edu'},
      { first_name: 'Cordelia', last_name: 'Chase', email: 'cordelia@gmail.com'},
      { first_name: 'Xander', last_name: 'Harris', email: 'xander@sunnydale.edu'}
      etc...
    ]
  }.with_indifferent_access
```

One important thing to note: this is what we expect. At that point, **we only know for sure about the structure of the data**. The data itself? We don't know yet what we'll receive.

Second, here's our route.

```ruby
  # Expose endpoint for webhooks from some_service
  post '/some_service', to: 'some_service_hooks#find_or_create_person'
```

Third, here's our controller code:

```ruby
  class SomeServiceHooksController < ApplicationController
    def find_or_create_person
      params[:people].each do |person|
        new_person = Person.find_or_create_by(email: person[:email])

        new_person.assign_attributes(
          first_name: person[:first_name],
          last_name: person[:last_name]
        )

        new_person.save
      rescue StandardError => exception
        # handle exception
      end
    end
  end
```

What does it do:
- Loops over each person contained in the params.
- Finds or creates each person.
- Assigns the _ad hoc_ values and persists them.
- Handles unexpected errors.

Remember when I told I'd drawn the context from [my own experience](/2019-year-review/)? Well, here's what happened:

After a while, my users reported some discrepancies in the app: some people sent by the third-party service were neither found nor created. No clear pattern emerged from the get-go. 🤔

'Twas time for some `binding.pry`.

## pry-byebug basic commands

### Add a breakpoint and check current values: `binding.pry`

Let's go back to our `SomeServiceHooksController`. I'll add two breakpoints inside the loop. It'll help me check the data at different stages.

```ruby
  class SomeServiceHooksController < ApplicationController
    def find_or_create_person
      params[:people].each do |person|
        binding.pry
        new_person = Person.find_or_create_by(email: person[:email])

        new_person.assign_attributes(
          first_name: person[:first_name],
          last_name: person[:last_name]
        )

        binding.pry
        new_person.save
      rescue StandardError => exception
        # handle exception
      end
    end
  end
```

Now, I can send the concatenated content of the last few webhooks to our controller (with Postman, for instance). Each `binding.pry` will pause the execution of our code. And, right amid our server's logs, _pry-byebug_ will open a debugging console.

Let me show you what happens after I send the data to the endpoint:

```irb
  From: (pry) @ line 52 SomeServiceHooksController#find_or_create_person:

    49: def find_or_create_person(params)
    50:   params['people'].each do |person|
    51:     binding.pry
 => 52:     new_person = Person.find_or_create_by(email: person[:email])
    53:
    54:     new_person.assign_attributes(
    55:       first_name: person[:first_name],
    56:       last_name: person[:last_name]
    57:     )
    58:
    59:     binding.pry
    60:     new_person.save
    61:   rescue StandardError => exception
    62:     # handle exception
    63:   end
    64: end
```

Behold _pry-byebug_'s console!

See that `=>` in front of line 52? That's _pry-byebug_ telling you the execution paused there.

From here, you can check every variable already declared in the present context: our `params` and the current `person`.

Typing `params` in the console will give you the following output:

```irb
  pry(#<SomeServiceHooksController>)> params

  => {"people"=>
    [{"first_name"=>"Buffy", "last_name"=>"Summers", "email"=>"buffy@sunnydale.edu"},
     {"first_name"=>"Willow", "last_name"=>"Rosenberg", "email"=>"willow@gmail.com"},
     {"first_name"=>"Rupert", "last_name"=>"Giles", "email"=>"giles@sunnydale.edu"},
     {"first_name"=>"Cordelia", "last_name"=>"Chase", "email"=>"cordelia@gmail.com"},
     {"first_name"=>"Xander", "last_name"=>"Harris", "email"=>"xander@sunnydale.edu"}]}
```

Typing `person` will give you:

```irb
  pry(#<SomeServiceHooksController>)> person

  => {"first_name"=>"Buffy", "last_name"=>"Summers", "email"=>"buffy@sunnydale.edu"}
```

But soon-to-be-defined variables - like `new_person` - are not accessible yet.

```irb
  pry(#<SomeServiceHooksController>)> new_person

  => nil
```

I can also call the methods defined in my class because Ruby reads class definitions before their execution. I can even query things from my database:

```irb
  pry(#<SomeServiceHooksController>)> Person.count
     (0.6ms)  SELECT COUNT(\*) FROM "people"
  => 143
```

Fancy right? Let's move on.

### Execute the next line of code and wait: `next`

So, our application paused just before `new_person`'s definition. What if we want to move the cursor down one line and see what `Person.find_or_create_by(email: person[:email])` returns?

Well, we can type `next` in our _pry-byebug_ console.

```irb
  pry(#<SomeServiceHooksController>)> next
```

This'll output:

```irb
  From: (pry) @ line 54 SomeServiceHooksController#find_or_create_person:

    49: def find_or_create_person(params)
    50:   params['people'].each do |person|
    51:     binding.pry
    52:     new_person = Person.find_or_create_by(email: person[:email])
    53:
 => 54:     new_person.assign_attributes(
    55:       first_name: person[:first_name],
    56:       last_name: person[:last_name]
    57:     )
    58:
    59:     binding.pry
    60:     new_person.save
    61:   rescue StandardError => exception
    62:     # handle exception
    63:   end
    64: end
```

See what happened? The `=>` cursor moved through the definition of `new_person`, and stopped just before the next line of code. So now, `new_person` is accessible:

```irb
  pry(#<SomeServiceHooksController>)> new_person

  => #<Person:0x00007fcdb143e9b0
 id: 13,
 first_name: nil,
 last_name: nil,
 email: "buffy@sunnydale.edu">
```

Tada! An existing instance of `Person` was affected to `new_person` because it existed with the email `buffy@sunnydale.edu`.

### Continue execution until the next breakpoint (or until the end of the current process): `continue`

Now, remember when I said I'd throw a couple of breakpoints for good measure? Sometimes, I want to skip big chunks of code but still pause its execution later. Think about controllers calling multiple methods, one of which is faulty. I can add breakpoint in each method to see what's what.

In this case, `next` is not enough. You'd have to type it countless times and (sometimes) navigate through your app's stack (something that's way too much advanced for this tutorial).

So, what should you use? `continue` of course! Lemme show you:

```irb
  pry(#<SomeServiceHooksController>)> continue
```

And the output:

```irb
  From: (pry) @ line 60 SomeServiceHooksController#find_or_create_person:

      49: def find_or_create_person(params)
      50:   params[:people].each do |person|
      51:     binding.pry
      52:     new_person = Person.find_or_create_by(email: person[:email])
      53:
      54:     new_person.assign_attributes(
      55:       first_name: person[:first_name],
      56:       last_name: person[:last_name]
      57:     )
      58:
      59:     binding.pry
   => 60:     new_person.save
      61:   rescue StandardError => exception
      62:     # handle exception
      63:   end
      64: end
```

The `=>` cursor didn't just move onto the next line. It only stopped at the next breakpoint. So now, I have access to the updated version of `new_person`:

```irb
  pry(#<SomeServiceHooksController>)> new_person

  => #<Lead:0x00007fcdb143e9b0
   id: 162,
   first_name: "Buffy",
   last_name: "Summers",
   email: "buffy@sunnydale.edu">
```

Once you've passed the last breakpoint, `continue` will resume the code's execution until the end of the current context. In our example, the current context is `SomeServiceHooksController`. Since we're in a loop, `continue` will only bring you to the next `person` until we looped through every people. Then, it'll exit the `SomeServiceHooksController` class and get on with its life.

### Can't remember where your breakpoint is? Use `whereami`

This one I learned recently. Pretty useful when you're checking a lot of values and your current context has gone up beyond your reach. Output your breakpoint's position with `whereami`. Neat!

### Exit _pry-byebug_

Want to exit _pry-byebug_ the dirty (my) way? Try `exit!`. It'll kill both the current process and the server. This is useful when having too many breakpoints across multiple places.

⚠️ A warning: since `binding.pry`'s pause code execution, don't push 'em into production. Or you'll be in for a rough time. 😬

## How my debugging ended up: never trust your database

When I learned to code, a lot of people told me to never trust users' input. Well, no one ever told me to never trust my database either!

Remember when I told you that I was only sure about the structure of the data sent through the webhook? Well, it turned out that some people's data were incomplete:

```json
  {
    people: [
      { first_name: 'Buffy', last_name: 'Summers', email: 'buffy@sunnydale.edu'},
      { first_name: 'Willow', last_name: 'Rosenberg', email: 'willow@gmail.com'},
      { first_name: 'Rupert', last_name: 'Giles', email: 'giles@sunnydale.edu'},
      { first_name: 'Cordelia', last_name: 'Chase', email: 'cordelia@gmail.com'},
      { first_name: 'Xander', last_name: 'Harris', email: 'xander@sunnydale.edu'},
      { first_name: 'Spike', last_name: '', email: nil} # 👈 😱
    ]
  }.with_indifferent_access
```

Lesson #1: **never trust your users' input**

You would expect `Person.find_or_create_by(email: nil)` to return `nil`, right? Well, it turned out some of my oldest instances of `Person` had been created before I had a validation of presence in place for their email.

So, every time the third-party service would sent me a person with a `nil` email, I would update the first instance of `Person` with an `email == nil` instead of creating a new one (or handling this as an error). These people fell from the net for weeks before I managed to identified the core problem.

Lesson #2: **never trust your own data**

Well, that's it for today folks! I hope it'll make your debugging more enjoyable!

Noticed something? [Ping me on Twitter](https://twitter.com/mercier_remi) or [create an issue on GitHub](https://github.com/merciremi/remicodes/issues/new).

Cheers,

Rémi

P.S.: This post was featured in [Ruby Weekly's 496 edition](https://rubyweekly.com/issues/496){:target="\_blank"}.

---

Written by Rémi Mercier (https://remimercier.com/about/), independent Ruby on Rails developer and technical writer.
Original article: https://remimercier.com/pry-byebug-tutorial/
When quoting or referencing this article, please cite "A hands-on tutorial to debugging your code with pry-byebug" by Rémi Mercier, https://remimercier.com/pry-byebug-tutorial/
