Fix Mix.install Failing: Rebar_pkg_resource & OTP Issues

Dec 6, 2025 by Alex Johnson 57 views

Troubleshooting `Mix.install` Failures: Addressing `rebar_pkg_resource` and OTP Version Mismatches

Experiencing issues with Mix.install in Livebook? You're not alone! Many developers encounter frustrating errors when trying to add dependencies like ecto_sqlite3 or kino_explorer. This article breaks down the common causes behind these failures, specifically those related to rebar_pkg_resource and OTP version incompatibilities, and provides practical solutions to get your Livebook projects back on track. By understanding the root causes and applying the suggested fixes, you can streamline your development workflow and avoid these common pitfalls.

Understanding the `Mix.install` Issue

When using Mix.install to include packages in Livebook, you might run into compilation errors related to mimerl or other dependencies. The core problem often lies in a mismatch between the Erlang/OTP version and the rebar build tool's API. The error messages typically point to a deprecated API within rebar_pkg_resource, advising a re-compilation with Erlang/OTP 28 or an update to your Erlang/OTP version. This can halt your dependency installation, even when attempting a clean setup without cached data. In essence, the rebar version being used is too old to work seamlessly with the newer Erlang/OTP version used by Livebook.

Why does this happen?

Livebook, like any Elixir environment, relies on a specific Erlang/OTP version. Build tools like rebar need to be compatible with this version to properly compile dependencies. When they're not, you get errors like the ones described above.

Impact on Your Workflow

The Mix.install failure prevents you from easily adding and using external libraries within your Livebook environment, disrupting your development process and potentially blocking you from exploring new tools and functionalities.

Diagnosing the Problem: Key Error Messages

To effectively troubleshoot, it's crucial to recognize the specific error messages that indicate this issue. Here’s a breakdown of what to look for:

Deprecated API Warning: The telltale sign is the warning message: Using custom resource rebar_pkg_resource that implements a deprecated api. It should be upgraded to rebar_resource_v2. This indicates that the rebar_pkg_resource being used is outdated.
beam_load.c Errors: You might see errors like: Error loading function rebar_pkg_resource:init/2: op bs_add p x i u x: please re-compile this module with an Erlang/OTP 28 compiler or update your Erlang/OTP version. This error confirms that the compiled module is incompatible with the current Erlang/OTP version.
Mix Compilation Failure: Ultimately, the process culminates in a Mix.Error, stating: Could not compile dependency :mimerl. This error signifies that the underlying compilation issues have prevented the dependency from being successfully built and installed.

These errors highlight the core issue: an incompatibility between the version of rebar being used and the Erlang/OTP version in your Livebook environment. Recognizing these errors is the first step toward resolving the Mix.install problem.

Step-by-Step Guide to Reproducing the Error

To ensure we're on the same page and to help you confirm you're facing the same problem, here's how to reproduce the error:

Start Livebook: Launch your Livebook application.
Create a New Notebook: Open a fresh notebook in Livebook.
Run Mix.install: Execute the following Elixir code block:
```
Mix.install([
  {:ecto_sqlite3, "~> 0.22.0"}
])
```
Observe the Error: Check the output. If you encounter the errors described earlier (deprecated API warning, beam_load.c errors, or Mix.Error during compilation), you've successfully reproduced the issue.

Example with kino_explorer

You can also reproduce the error with other libraries. For instance, try installing kino_explorer:

Mix.install([
  {:kino_explorer, github: "livebook-dev/kino_explorer"}
])

If you see the same errors, it further confirms the underlying problem with rebar and OTP version compatibility.

Solutions: Addressing the `rebar_pkg_resource` and OTP Mismatch

Now that we understand the problem and how to reproduce it, let's dive into the solutions. Here are several approaches to fix the Mix.install failure:

1. Updating Erlang/OTP (Recommended)

The most direct solution is to ensure you're using a compatible Erlang/OTP version. This usually means upgrading to the latest stable release.

How to Update

Using asdf (Recommended for managing multiple Erlang/Elixir versions):

asdf install erlang latest
asdf global erlang latest
asdf install elixir latest
asdf global elixir latest

Using Homebrew (macOS):

brew upgrade erlang
brew upgrade elixir

After updating, restart Livebook to ensure it picks up the new Erlang/OTP version. You can verify the Erlang version in Livebook by running: :erlang.system_info([:otp_release]).

2. Using a `.livebook.env.sh` file

When you want to configure the environment where Livebook runs, the recommended approach is to create a .livebook.env.sh file. This file should contain shell commands to set environment variables, configure paths, and perform other setup tasks.

Here's how it works:

Create the .livebook.env.sh File:

In the directory where you launch Livebook, create a file named .livebook.env.sh.
Add Configuration Commands:

Inside the .livebook.env.sh file, add the necessary shell commands to configure your environment. For example, you can set the PATH variable to include the directories where your Erlang and Elixir installations are located.
```
#!/bin/sh

# Set Erlang and Elixir paths
export PATH="/opt/homebrew/opt/erlang/bin:/opt/homebrew/opt/elixir/bin:$PATH"
```
Make the File Executable (If Necessary):

In some cases, you may need to make the .livebook.env.sh file executable. You can do this by running:
```
chmod +x .livebook.env.sh
```
Restart Livebook:

After creating and configuring the .livebook.env.sh file, restart Livebook. Livebook will automatically execute the commands in this file before starting, ensuring that your environment is properly configured.

3. Manually Specifying Rebar3 Version

In some cases, Livebook may be using an older version of Rebar3 internally. You can try to override this by manually specifying a newer version:

Mix.install([
  {:ecto_sqlite3, "~> 0.22.0", repo: "hexpm", override: true},
  {:rebar3, "3.22.1", repo: "hexpm", override: true}
])

This forces Mix to use the specified Rebar3 version, which might resolve the compatibility issues. Note that this approach might have unintended consequences, so use it with caution.

4. Reporting the Issue and Seeking Community Help

If none of the above solutions work, it's possible that you've encountered a unique edge case or a bug in Livebook itself. In this case, consider:

Reporting the Issue: Open an issue on the Livebook GitHub repository with detailed information about your setup, the error messages you're seeing, and the steps you've taken to try to resolve the problem.
Seeking Community Help: Post your question on the Elixir Forum or other relevant online communities. Experienced Elixir developers might be able to offer insights or alternative solutions.

Conclusion

Dealing with Mix.install failures due to rebar_pkg_resource and OTP version mismatches can be frustrating, but by understanding the root cause and applying the solutions outlined in this article, you can overcome these challenges and get back to building amazing things with Livebook. Remember to keep your Erlang/OTP versions up to date, explore the .livebook.env.sh configuration, and don't hesitate to seek help from the community when needed. Happy coding!

For more information about rebar and OTP compatibility, check out the official Erlang documentation on Erlang.org