TimeoutError
modal.client.exceptions.TimeoutError
Stack trace
modal.client.exceptions.TimeoutError: Function deployment timed out after 300 seconds
File "/usr/local/lib/python3.9/site-packages/modal/client.py", line 512, in deploy
raise TimeoutError("Function deployment timed out after 300 seconds") Why it happens
Modal deploy timeout occurs when the function build or container startup takes longer than the configured timeout period, often due to large dependencies, slow network, or heavy initialization code. The deployment process waits for the function to become ready but aborts after the timeout.
Detection
Monitor deployment logs and catch modal.client.exceptions.TimeoutError exceptions during deploy calls to detect when deployment exceeds the timeout threshold.
Causes & fixes
Large or numerous dependencies cause slow container build and startup.
Optimize your Dockerfile or requirements to reduce dependency size and build time, or pre-build and cache images if supported.
Heavy initialization code in the function delays readiness beyond timeout.
Refactor initialization to be lazy or faster, or move heavy setup outside the function deploy path.
Network slowness or connectivity issues delay deployment steps.
Check network stability and retry deployment in a better network environment.
Default deployment timeout is too short for your function's build and startup time.
Increase the deployment timeout setting in your Modal client configuration if supported.
Code: broken vs fixed
import modal
stub = modal.Stub()
@stub.function
async def my_function():
# some code
stub.deploy() # This line raises TimeoutError after waiting too longimport os
import modal
os.environ["MODAL_API_KEY"] = os.getenv("MODAL_API_KEY") # Ensure API key is set
stub = modal.Stub()
@stub.function
async def my_function():
# some code
# Increase timeout or optimize function to avoid timeout
stub.deploy(timeout=600) # Increased timeout to 600 secondsWorkaround
Wrap the deploy call in try/except modal.client.exceptions.TimeoutError, then retry deployment or alert the user to try again later.
Prevention
Design functions with minimal startup overhead and optimize dependencies; configure deployment timeout settings appropriately to avoid hitting timeouts.