/ Docs


This page contains tips for troubleshooting DipDup issues. Start with "General" section and then proceed to one that matches your problem.


Update DipDup to the latest version

If you experience an issue, first of all, make sure that you're using the latest version of DipDup. If a new release is available you'll see a warning message when running DipDup. You can update DipDup using the following commands depending on your installation method:

# Built-in installer
dipdup self update

# pipx
pipx upgrade dipdup

pdm update

# Poetry
poetry update

# pip
pip install --upgrade dipdup

When using Docker images you can use X and X.Y tags to lock to specific major/minor releases:

FROM dipdup/dipdup:7

We follow semantic versioning, so you can safely update to a new patch version without any breaking changes.

Enable debug logging

More logs can give you a clue about the reason for an issue. Enable them in config:

logging: DEBUG



Ensure that config is correct

DipDup config can be correct syntactically but not necessarily semantically. It's especially easy to make a mistake when actively using templates and environment variables. Use config export command to dump config the way DipDup "sees" it, after resolving all links and templates.

dipdup -c . -c configs/dipdup.sqlite.yaml config export

Check env variables

config env command can help you to find missing environment variables.

dipdup -c . -c configs/dipdup.sqlite.yaml config env


Use linters to find errors in your Python code

Exceptions that occurred during callback execution are reraised as CallbackErrors. If you experience this issue, most likely your code is incorrect. Luckily, the Python ecosystem has lots of tools called linters to help you find mistakes. Default DipDup project template includes black, ruff and mypy to check your code for errors and type mismatches. You can run them with the following commands:

pdm format
pdm lint

# Manually
black .
ruff --fix .
mypy .

See the pyproject.toml file in your project root for more details.

Inspect the package structure


Tezos: explorers

Better Call Dev is a blockchain explorer for Tezos smart contracts. It provides a more human-friendly interface than TzKT to explore exact contract calls and parameter/storage structures.


Try it out when writing index definitions.

Found a bug?

When an exception occurs DipDup saves crash dumps to ~/local/share/dipdup/reports. You can inspect them using dipdup report ls and dipdup report show commands.

If you think you've found a bug, please report it directly to the GitHub Issues. For all other discussions.

Got stuck?

Ask for help! We are always ready to answer your questions.

join our socials:

Help and tips -> Join our Discord
Ideas or suggestions -> Issue Tracker