ModalBuildError
modal.exception.ModalBuildError
Stack trace
modal.exception.ModalBuildError: Image build failed: Could not resolve dependency 'some-package==1.2.3'.
Check your requirements.txt or Dockerfile for missing or conflicting packages.
at modal.image.build (modal/image.py:123)
at modal.app.deploy (modal/app.py:45)
at main.py:10 Why it happens
Modal builds container images by installing dependencies declared in your requirements.txt or Dockerfile. If a dependency version is missing, incompatible, or the package repository is unreachable, the build process fails with this error. This often happens when dependencies are not pinned correctly or external package sources are down.
Detection
Monitor Modal image build logs for 'Could not resolve dependency' messages and catch ModalBuildError exceptions during deployment to identify dependency resolution failures early.
Causes & fixes
A required Python package version is not available or misspelled in requirements.txt
Verify and correct the package names and versions in requirements.txt to match valid releases on PyPI.
The Dockerfile or image build config references system packages that are missing or incompatible
Ensure all system-level dependencies are installed via apt-get or equivalent commands in the Dockerfile before Python package installation.
Network issues prevent access to package repositories during image build
Check network connectivity and proxy settings in the build environment to allow access to PyPI or other package sources.
Using conflicting dependency versions that cannot be resolved together
Pin compatible versions of dependencies and test locally with a clean environment before deploying the Modal image build.
Code: broken vs fixed
import modal
stub = modal.Stub()
@stub.function(
image=modal.Image.from_dockerfile("./", build_args={"SOME_ARG": "value"})
)
def my_function():
pass
if __name__ == "__main__":
stub.deploy() # This line triggers ModalBuildError due to dependency issuesimport os
import modal
os.environ["MODAL_API_KEY"] = os.environ.get("MODAL_API_KEY") # Use env var for auth
stub = modal.Stub()
# Fixed: Pin dependencies in requirements.txt and ensure Dockerfile installs system deps
@stub.function(
image=modal.Image.from_dockerfile("./", build_args={"SOME_ARG": "value"})
)
def my_function():
pass
if __name__ == "__main__":
stub.deploy() # Fixed: build succeeds with correct dependencies
print("Modal image deployed successfully.")Workaround
Manually build the Docker image locally with the same Dockerfile and requirements.txt to identify and fix dependency issues before deploying with Modal.
Prevention
Use strict dependency pinning in requirements.txt, include all system dependencies in the Dockerfile, and test image builds locally or in CI before deploying with Modal to avoid build failures.