7.2 Debugging with Aleoscan Explorer

Alright, time to roll up our sleeves and get into one of the most practical tools you’ll use when debugging Leo programs: the Aleoscan Explorer. If you've ever hit an error in an on-chain transition, say, a failed assert or a missing mapping key, you know how frustrating it can be to figure out why something failed. The Aleoscan Explorer will help you see what happened and where it happened. It also shows all the public state updates, transition input/outputs, and more generally all the chain data you will need, represented on a frontend.

Not only is it available for Testnet and Mainnet, but it is also open source so you can run your own instance, for your local Devnet for instance.

Why Use Aleoscan Explorer?

Once you start writing complex programs, maybe with multiple transitions, nested calls, or non-trivial staten you’re going to want a good tool for inspecting blockchain data.

Let’s say your program fails with a cryptic error like “transaction rejected” Okay, but what happended? maybe a mapping key wasn't found? which mapping? What key? Where did it fail? CLI tools won’t give you that kind of detail. But the Aleoscan Explorer will. It indexes blockchain state into a database and lets you browse it with a frontend interface. You can see transactions, debug errors, inspect mappings, basically, get a full picture of what’s going on.

Running Aleoscan Explorer Locally

The Aleoscan Explorer is open source, and the team behind it has made it easy to spin up using Docker. Here’s a quick walkthrough:

Step 1: Clone the Repository

git clone https://github.com/AleoHQ/aleo-explorer.git
cd aleo-explorer

You’ll want to use the mainnet-newdb branch, since it stores nearly all blockchain data in Postgres, with no Redis dependency.

git checkout mainnet-newdb

Step 2: Start the Explorer

Make sure Docker is installed and running on your system. Then fire it up:

docker-compose up -d

This will start several services:

• A backend node that connects to your local Aleo node

• A Postgres database to index blockchain data

• A frontend served locally (usually on http://localhost:8800)

⚠️ Pro tip: Let it run for a bit. It’ll take some time to sync data from your devnet.

What’s Actually Happening Behind the Scenes?

The explorer connects to your Aleo node and listens for new blocks. As they come in, it parses transactions, transitions, and state changes—then stores everything in Postgres. That means:

• You don’t need to query every transaction manually to understand the state

• You can search, filter, and view data instantly through the frontend

• You get a full historical snapshot of your blockchain's state

Debugging a Failing Transaction

Let’s walk through a real example.

I deployed a simple NFT program that includes a mint transition. Everything looked fine, until I tried minting a second token and the transaction failed.

So I opened up http://localhost:8800 and searched for the failed transaction. Sure enough, there it was, clearly marked as Rejected.

Clicking into the transaction, I saw a helpful error message:

“Mapping key not found in transition 0.”

That’s already a major win. Now I know:

• The failure occurred in transition index 0

• The cause was a missing mapping key

The explorer even showed me which instruction inside the transition caused the problem. It was an assert that checked if a key existed in a mapping.

assert(account_balances.get(owner) == aleo1...);

At this point, I can take the program ID and go look up the source code of that transition. I find the instruction in question and see that I was referencing a key that hadn’t been initialized yet.

Digging Deeper: Mappings and State Changes

One of the best features of Aleoscan is its ability to show all mapping operations. For any transaction, you can see:

• What keys were added or removed from a mapping

• Which accounts had their state updated

• Any fees deducted

• A mapping value was deleted

So if you’re debugging something like a state mutation or access control check, this is pure gold. You can trace the lifecycle of a mapping key, from creation to deletion, across transitions.

Want to know what value was stored at a key? Just click it. Need to verify a balance was updated? It’s right there.

What If I Want to Query Directly?

The explorer backend exposes an API too. So if you’re more into scripts than GUIs, you can hit the same endpoints the frontend uses. That means you can write custom tooling on top of it later if you want.

This is where your skills start to level up. You're not just coding, you’re investigating!