Files
skills/public/modal-modal-common-errors.html
zeekayandHanzo Dev 9e10c1c10e Each llms index points at the other two
hanzoskills.com/llms.txt now opens with the install line, the API
reference index and the company index, so an agent that lands on any
one of the three can find the rest.

robots.txt claimed 537 documents while llms.txt counts 920. The number
is gone from robots.txt; llms.txt derives it.

public/ is regenerated from scripts/site.py, which it had fallen
behind: the copy-prompt menu and agent bar were in the generator and
not in the committed pages. tests/site.mjs passes against the result.

Co-authored-by: Hanzo Dev <[email protected]>
2026-09-11 00:27:59 -07:00

536 lines
27 KiB
HTML

<!doctype html>
<html lang="en"><head>
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
<title>modal-modal-common-errors</title>
<meta name="color-scheme" content="dark">
<style>
/* Committed to one visual world: a dark instrument panel. No light variant —
the dot field and the hairline rules only read on black, and a naive
inversion would wash both out. Every colour is painted explicitly so the page
never borrows a host background. */
@font-face{font-family:'Zen';src:url('/fonts/Zen-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen';src:url('/fonts/Zen-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Pixel Square';src:url('/fonts/ZenPixel-Square.woff2') format('woff2');font-style:normal;font-display:swap}
:root{
--ink:#f4f4f2; --soft:#9c9c98; --faint:#6a6a66; --ground:#000; --panel:#0a0a0a;
--line:#232323; --line-hi:#3a3a3a; --accent:#f4f4f2;
--font-zen-sans:'Zen',-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif;
--font-zen-mono:'Zen Mono',ui-monospace,"SF Mono",SFMono-Regular,Menlo,Consolas,monospace;
--font-zen-pixel-square:'Zen Pixel Square',monospace;
--mono:var(--font-zen-mono);
--sans:var(--font-zen-sans);
/* Controls are pills and surfaces are soft, as on hanzo.ai. */
--r:999px; --r-soft:14px;
}
*{box-sizing:border-box}
html{-webkit-text-size-adjust:100%}
body{margin:0;background:var(--ground);color:var(--ink);font-family:var(--sans);
font-size:16px;line-height:1.65;-webkit-font-smoothing:antialiased}
.wrap{max-width:60rem;margin:0 auto;padding:0 1.75rem}
/* The dot field. A halftone made of one repeating radial-gradient, faded out
along the diagonal by a mask so it reads as a wave rather than wallpaper. */
/* No overflow clip here: the dot field is inset to the box already, and a clip
would cut off the copy-prompt menu. */
.hero{position:relative;border-bottom:1px solid var(--line)}
.hero::before{content:"";position:absolute;inset:0;
background-image:radial-gradient(var(--line-hi) 1px, transparent 1px);
background-size:7px 7px;
-webkit-mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
pointer-events:none}
.hero .wrap{position:relative;padding-top:5.5rem;padding-bottom:4rem}
nav{border-bottom:1px solid var(--line)}
nav .in{max-width:60rem;margin:0 auto;padding:1.1rem 1.75rem;display:flex;
justify-content:space-between;align-items:center;gap:1rem}
.brand{font-family:var(--mono);font-size:.85rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--ink);text-decoration:none;
display:inline-flex;align-items:center;gap:.6rem}
.brand i{font-style:normal;color:var(--faint)}
.mark{width:1.15em;height:1.15em;display:block;flex:0 0 auto}
nav a.up{font-family:var(--mono);font-size:.72rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--soft);text-decoration:none}
nav a.up:hover{color:var(--ink)}
h1{font-family:var(--mono);font-size:clamp(2rem,5.4vw,3.4rem);line-height:1.12;
letter-spacing:-.02em;margin:0 0 1.1rem;font-weight:500;text-wrap:balance}
h1 em{font-style:normal;color:var(--faint)}
.lede{color:var(--soft);font-size:1.05rem;max-width:52ch;margin:0 0 2.25rem}
.btns{display:flex;flex-wrap:wrap;gap:.7rem;margin:0 0 .5rem;align-items:center}
.btn{display:inline-flex;align-items:center;gap:.5rem;font-family:var(--mono);
font-size:.72rem;letter-spacing:.14em;text-transform:uppercase;
padding:.8rem 1.4rem;border:1px solid var(--line-hi);border-radius:var(--r);
color:var(--ink);text-decoration:none;background:transparent;cursor:pointer;
line-height:1.2;font-weight:400}
.btn:hover{background:#141414;text-decoration:none;border-color:var(--soft)}
.btn.solid{background:var(--ink);color:#000;border-color:var(--ink)}
.btn.solid:hover{background:#d8d8d4}
.btn .chev{width:.7em;height:.7em;flex:0 0 auto;transition:transform .15s ease}
.btn[aria-expanded="true"] .chev{transform:rotate(180deg)}
/* Copy-prompt selector. Each row copies the prompt for its own target. */
.copy{position:relative;display:inline-flex}
.menu{position:absolute;top:calc(100% + .5rem);left:0;z-index:20;min-width:21rem;
background:var(--panel);border:1px solid var(--line-hi);border-radius:var(--r-soft);
padding:.4rem;display:flex;flex-direction:column;
box-shadow:0 12px 32px rgba(0,0,0,.75)}
.menu[hidden]{display:none}
.mi{display:flex;align-items:center;gap:.7rem;width:100%;text-align:left;
padding:.62rem .8rem;border:0;border-radius:calc(var(--r-soft) - .35rem);
background:transparent;color:var(--ink);font-family:var(--mono);font-size:.76rem;
letter-spacing:.04em;text-decoration:none;cursor:pointer;line-height:1.3;
white-space:nowrap}
.mi:hover,.mi:focus-visible{background:#181818;outline:none}
.mi .mark{width:1.05rem;height:1.05rem;color:var(--soft)}
.mi:hover .mark{color:var(--ink)}
.mi u{margin-left:auto;color:var(--faint);text-decoration:none;font-size:.68rem;
letter-spacing:.1em;text-transform:uppercase}
/* Works-with bar: one scrolling row, name and mark per agent. */
.strip{border-bottom:1px solid var(--line);background:var(--panel)}
.strip .in{max-width:60rem;margin:0 auto;padding:.9rem 1.75rem;display:flex;
align-items:center;gap:1.25rem;font-family:var(--mono);font-size:.72rem;
letter-spacing:.1em;text-transform:uppercase;color:var(--faint)}
.strip b{color:var(--soft);font-weight:400;flex:0 0 auto;
border-right:1px solid var(--line);padding-right:1.25rem;align-self:stretch;
display:flex;align-items:center}
.bar{display:flex;align-items:center;gap:.5rem;flex:1 1 auto;min-width:0;
overflow-x:auto;scrollbar-width:none;scroll-snap-type:x proximity;
-webkit-overflow-scrolling:touch;
-webkit-mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent);
mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent)}
.bar::-webkit-scrollbar{display:none}
.agent{display:inline-flex;align-items:center;gap:.45rem;flex:0 0 auto;
padding:.4rem .85rem;border:1px solid var(--line);border-radius:var(--r);
color:var(--soft);white-space:nowrap;scroll-snap-align:start;
text-decoration:none;background:var(--ground)}
.agent:hover{color:var(--ink);border-color:var(--line-hi);text-decoration:none}
.agent .mark{width:.95rem;height:.95rem}
h2{font-family:var(--mono);font-size:1.1rem;letter-spacing:-.01em;margin:2.75rem 0 .75rem;font-weight:500}
h3{font-size:1rem;margin:2rem 0 .5rem;font-weight:600}
h4,h5,h6{font-size:.94rem;margin:1.5rem 0 .5rem;font-weight:600}
p{margin:0 0 1rem;max-width:70ch}
ul,ol{margin:0 0 1rem;padding-left:1.35rem;max-width:70ch}
li{margin:.22rem 0}
a{color:var(--ink);text-decoration:underline;text-underline-offset:3px;
text-decoration-color:var(--line-hi)}
a:hover{text-decoration-color:var(--ink)}
a:focus-visible{outline:1px solid var(--ink);outline-offset:3px}
code{font-family:var(--mono);font-size:.85em;background:var(--panel);
border:1px solid var(--line);border-radius:5px;padding:.1em .36em}
pre{background:var(--panel);border:1px solid var(--line);padding:1rem 1.1rem;
border-radius:var(--r-soft);overflow-x:auto;margin:0 0 1.25rem}
pre code{background:none;border:0;padding:0;font-size:.82rem;line-height:1.7}
blockquote{margin:0 0 1rem;padding-left:1rem;border-left:1px solid var(--line-hi);color:var(--soft)}
hr{border:0;border-top:1px solid var(--line);margin:2.5rem 0}
table{border-collapse:collapse;width:100%;margin:0 0 1.25rem;font-size:.92rem;
display:block;overflow-x:auto}
th,td{border:1px solid var(--line);padding:.5rem .7rem;text-align:left}
.curl{display:block;background:var(--panel);border:1px solid var(--line);
border-radius:var(--r-soft);padding:.95rem 1.1rem;font-family:var(--mono);
font-size:.8rem;color:var(--soft);overflow-x:auto;margin:0 0 2.5rem;
white-space:pre;line-height:1.9}
.curl b{color:var(--ink);font-weight:400}
.curl i{font-style:normal;color:var(--faint)}
/* index */
#q{width:100%;padding:.85rem 1.2rem;font-family:var(--mono);font-size:.85rem;color:var(--ink);
background:var(--panel);border:1px solid var(--line);border-radius:var(--r);margin:0 0 .6rem}
#q::placeholder{color:var(--faint);text-transform:uppercase;letter-spacing:.1em;font-size:.72rem}
#q:focus{outline:none;border-color:var(--soft)}
#count{color:var(--faint);font-family:var(--mono);font-size:.72rem;letter-spacing:.1em;
text-transform:uppercase;margin:0 0 2rem}
.cat{margin:2.5rem 0 .5rem;font-family:var(--mono);font-size:.7rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);border-bottom:1px solid var(--line);
padding-bottom:.45rem}
.row{display:block;padding:.6rem .9rem;margin:0 -.9rem;border-bottom:1px solid var(--line);
border-radius:var(--r-soft);text-decoration:none}
.row:hover{background:#0a0a0a}
.nm{font-family:var(--mono);font-size:.84rem;color:var(--ink);display:block}
.ds{color:var(--soft);font-size:.9rem;display:block;margin-top:.12rem}
footer{margin-top:4rem;padding:2rem 0 4rem;border-top:1px solid var(--line);
color:var(--faint);font-size:.85rem}
footer a{color:var(--soft)}
.fmap{display:grid;gap:1.75rem;grid-template-columns:repeat(auto-fit,minmax(11rem,1fr));
margin:0 0 2rem;font-size:.85rem}
.fmap b{display:block;font-family:var(--mono);font-size:.68rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);font-weight:400;margin:0 0 .6rem;
border-bottom:1px solid var(--line);padding-bottom:.4rem}
.fmap a{display:inline-block;color:var(--ink);text-decoration:none;margin:.3rem .35rem 0 0}
.fmap a:hover{text-decoration:underline}
.fmap div{color:var(--faint);line-height:1.5}
.fend{border-top:1px solid var(--line);padding-top:1.25rem;font-size:.82rem}
@media (max-width:640px){
.hero .wrap{padding-top:3.25rem;padding-bottom:2.75rem}
.btns{gap:.5rem}
.btn{padding:.75rem 1.15rem;font-size:.68rem}
.copy,.copy .btn{width:100%;justify-content:center}
.menu{left:0;right:0;min-width:0}
.strip .in{flex-direction:column;align-items:flex-start;gap:.6rem;padding:.9rem 1.75rem}
.strip b{border-right:0;padding-right:0}
.bar{width:100%}
}
</style>
<link rel="alternate" type="text/markdown" href="/modal-modal-common-errors.md">
<link rel="icon" href="/favicon.svg">
<link rel="canonical" href="https://hanzoskills.com/modal-modal-common-errors">
</head>
<!-- Reading this with a machine? Every page here is also plain markdown.
This one: https://hanzoskills.com/modal-modal-common-errors.md
Index: https://hanzoskills.com/llms.txt
Corpus: https://hanzoskills.com/all.md
Append .md to any path for the markdown twin. -->
<body>
<nav><div class="in">
<a class="brand" href="/"><svg class="mark" viewBox="0 0 67 67" fill="currentColor" aria-hidden="true"><path d="M22.21 67V44.6369H0V67H22.21Z"/><path d="M66.7038 22.3184H22.2534L0.0878906 44.6367H44.4634L66.7038 22.3184Z"/><path d="M22.21 0H0V22.3184H22.21V0Z"/><path d="M66.7198 0H44.5098V22.3184H66.7198V0Z"/><path d="M66.7198 67V44.6369H44.5098V67H66.7198Z"/></svg> HANZO<i>SKILLS</i></a>
<a class="up" href="/">All skills</a>
</div></nav>
<div class="wrap">
<h1>modal-modal-common-errors</h1><p class="lede">Encountering Modal deployment or runtime errors</p><h1>Modal Common Errors</h1>
<p><strong>Scope</strong>: Common Modal.com errors, debugging strategies, and proven solutions <strong>Lines</strong>: ~340 <strong>Last Updated</strong>: 2025-10-18</p>
<h2>When to Use This Skill</h2>
<p>Activate this skill when:</p>
<ul><li>Encountering Modal deployment or runtime errors</li><li>Debugging failed Modal function executions</li><li>Resolving image build failures</li><li>Fixing import and dependency errors</li><li>Troubleshooting timeout and memory issues</li><li>Solving GPU allocation problems</li><li>Debugging network and connection errors</li></ul>
<h2>Core Concepts</h2>
<h3>Error Categories</h3>
<p><strong>Build-time errors</strong>: Occur during image building</p>
<ul><li>Package installation failures</li><li>Dependency conflicts</li><li>Invalid Dockerfile syntax</li><li>Missing system dependencies</li><li>Network timeouts during build</li></ul>
<p><strong>Runtime errors</strong>: Occur during function execution</p>
<ul><li>Import errors (module not found)</li><li>Timeout errors (function exceeded limit)</li><li>Memory errors (OOM)</li><li>GPU allocation failures</li><li>Permission errors</li></ul>
<p><strong>Deployment errors</strong>: Occur during app deployment</p>
<ul><li>Invalid app configuration</li><li>Authentication failures</li><li>Resource quota exceeded</li><li>Invalid decorator usage</li></ul>
<h3>Debugging Strategy</h3>
<p><strong>Step 1: Identify error phase</strong></p>
<ul><li>Build time → Check image configuration</li><li>Runtime → Check function code and dependencies</li><li>Deployment → Check app structure and auth</li></ul>
<p><strong>Step 2: Read error messages carefully</strong></p>
<ul><li>Modal provides detailed stack traces</li><li>Look for root cause (not just last line)</li><li>Check for common patterns</li></ul>
<p><strong>Step 3: Use debugging tools</strong></p>
<ul><li><code>modal shell</code> for interactive debugging</li><li><code>modal logs</code> for historical debugging</li><li>Local testing with <code>modal run --dev</code></li></ul>
<hr>
<h2>Patterns</h2>
<h3>Image Build Errors</h3>
<h4>Error: &quot;ModuleNotFoundError&quot; at runtime</h4>
<pre><code>ERROR: ModuleNotFoundError: No module named &#x27;requests&#x27;</code></pre>
<p><strong>Cause</strong>: Package not installed in Modal image</p>
<p><strong>Solution</strong>:</p>
<pre><code class="lang-python"># ❌ Bad: Package not in image
@app.function()
def fetch_data():
import requests # Will fail!
return requests.get(&quot;https://api.example.com&quot;).json()
# ✅ Good: Install package in image
image = modal.Image.debian_slim().uv_pip_install(&quot;requests&quot;)
@app.function(image=image)
def fetch_data():
import requests
return requests.get(&quot;https://api.example.com&quot;).json()</code></pre>
<h4>Error: &quot;Package installation failed&quot;</h4>
<pre><code>ERROR: Could not find a version that satisfies the requirement numpy==2.0.0</code></pre>
<p><strong>Cause</strong>: Invalid version or package name</p>
<p><strong>Solution</strong>:</p>
<pre><code class="lang-python"># ❌ Bad: Wrong version or typo
image = modal.Image.debian_slim().uv_pip_install(
&quot;numpy==2.0.0&quot;, # Version doesn&#x27;t exist
&quot;pandass&quot; # Typo
)
# ✅ Good: Verify versions and names
image = modal.Image.debian_slim().uv_pip_install(
&quot;numpy==1.26.0&quot;, # Valid version
&quot;pandas==2.1.0&quot; # Correct spelling
)</code></pre>
<p><strong>Debugging tip</strong>: Test packages locally first with <code>uv pip install</code></p>
<h4>Error: &quot;System dependency missing&quot;</h4>
<pre><code>ERROR: ImportError: libGL.so.1: cannot open shared object file</code></pre>
<p><strong>Cause</strong>: Missing system library (common with OpenCV, etc.)</p>
<p><strong>Solution</strong>:</p>
<pre><code class="lang-python"># ❌ Bad: Only Python package
image = modal.Image.debian_slim().uv_pip_install(&quot;opencv-python&quot;)
# ✅ Good: Install system dependencies first
image = (
modal.Image.debian_slim()
.apt_install(&quot;libgl1-mesa-glx&quot;, &quot;libglib2.0-0&quot;)
.uv_pip_install(&quot;opencv-python&quot;)
)</code></pre>
<h3>Runtime Errors</h3>
<h4>Error: &quot;TimeoutError&quot;</h4>
<pre><code>ERROR: Function exceeded timeout of 60 seconds</code></pre>
<p><strong>Cause</strong>: Function ran longer than timeout limit (default 60s)</p>
<p><strong>Solution</strong>:</p>
<pre><code class="lang-python"># ❌ Bad: Default timeout too short
@app.function()
def train_model():
# Takes 5 minutes
model.fit(X_train, y_train)
return model
# ✅ Good: Set appropriate timeout
@app.function(timeout=600) # 10 minutes
def train_model():
model.fit(X_train, y_train)
return model</code></pre>
<p><strong>Timeout limits</strong>:</p>
<ul><li>Default: 60 seconds</li><li>Maximum: 86400 seconds (24 hours)</li><li>Best practice: Set 20% higher than expected runtime</li></ul>
<h4>Error: &quot;OutOfMemoryError&quot;</h4>
<pre><code>ERROR: Container killed due to OOM (Out of Memory)</code></pre>
<p><strong>Cause</strong>: Function exceeded memory limit</p>
<p><strong>Solution</strong>:</p>
<pre><code class="lang-python"># ❌ Bad: Default memory (1GB) insufficient
@app.function()
def process_large_file():
df = pd.read_csv(&quot;huge_file.csv&quot;) # 5GB file
return df.shape
# ✅ Good: Increase memory limit
@app.function(memory=8192) # 8GB RAM
def process_large_file():
df = pd.read_csv(&quot;huge_file.csv&quot;)
return df.shape
# ✅ Better: Stream data instead
@app.function(memory=2048)
def process_large_file_streaming():
chunks = pd.read_csv(&quot;huge_file.csv&quot;, chunksize=10000)
total_rows = sum(len(chunk) for chunk in chunks)
return total_rows</code></pre>
<h4>Error: &quot;GPUOutOfMemoryError&quot;</h4>
<pre><code>ERROR: CUDA out of memory. Tried to allocate 2.00 GiB</code></pre>
<p><strong>Cause</strong>: Model or batch size too large for GPU memory</p>
<p><strong>Solution</strong>:</p>
<pre><code class="lang-python"># ❌ Bad: Batch size too large
@app.function(gpu=&quot;A10G&quot;) # 24GB VRAM
def train():
batch_size = 128 # Too large
train_loader = DataLoader(dataset, batch_size=batch_size)
# OOM error
# ✅ Good: Reduce batch size
@app.function(gpu=&quot;A10G&quot;)
def train():
batch_size = 32 # Fits in memory
train_loader = DataLoader(dataset, batch_size=batch_size)
# ✅ Better: Use gradient accumulation
@app.function(gpu=&quot;A10G&quot;)
def train():
batch_size = 16
accumulation_steps = 4 # Effective batch size = 64
train_loader = DataLoader(dataset, batch_size=batch_size)</code></pre>
<h3>Import and Dependency Errors</h3>
<h4>Error: &quot;Relative import error&quot;</h4>
<pre><code>ERROR: ImportError: attempted relative import with no known parent package</code></pre>
<p><strong>Cause</strong>: Relative imports don&#x27;t work in Modal&#x27;s execution model</p>
<p><strong>Solution</strong>:</p>
<pre><code class="lang-python"># ❌ Bad: Relative imports
from .utils import helper_function
from ..models import Model
# ✅ Good: Absolute imports or inline code
# Option 1: Include code in same file
@app.function()
def helper_function():
return &quot;helper&quot;
@app.function()
def main():
result = helper_function.remote()
# Option 2: Use Modal&#x27;s mount feature
from modal import Mount
@app.function(
mounts=[Mount.from_local_dir(&quot;./src&quot;, remote_path=&quot;/root/src&quot;)]
)
def main():
import sys
sys.path.append(&quot;/root/src&quot;)
from utils import helper_function</code></pre>
<h4>Error: &quot;NameError: name &#x27;X&#x27; is not defined&quot;</h4>
<pre><code>ERROR: NameError: name &#x27;MY_CONSTANT&#x27; is not defined</code></pre>
<p><strong>Cause</strong>: Global variables not available in Modal functions</p>
<p><strong>Solution</strong>:</p>
<pre><code class="lang-python"># ❌ Bad: Global variable
MY_CONSTANT = 42
@app.function()
def use_constant():
return MY_CONSTANT # Not available!
# ✅ Good: Pass as parameter or use class
@app.function()
def use_constant(constant: int = 42):
return constant
# ✅ Better: Use app.cls for state
@app.cls()
class MyService:
def __init__(self):
self.constant = 42
@modal.method()
def use_constant(self):
return self.constant</code></pre>
<h3>Network and Connection Errors</h3>
<h4>Error: &quot;ConnectionError: Failed to connect&quot;</h4>
<pre><code>ERROR: requests.exceptions.ConnectionError: Failed to establish connection</code></pre>
<p><strong>Cause</strong>: Network issues, firewall, or service unavailable</p>
<p><strong>Solution</strong>:</p>
<pre><code class="lang-python"># ❌ Bad: No retry logic
@app.function()
def fetch_data():
response = requests.get(&quot;https://api.example.com/data&quot;)
return response.json()
# ✅ Good: Add retries and timeout
from tenacity import retry, stop_after_attempt, wait_exponential
@app.function(timeout=300)
@retry(
stop=stop_after_attempt(3),
wait=wait_exponential(multiplier=1, min=4, max=10)
)
def fetch_data():
response = requests.get(
&quot;https://api.example.com/data&quot;,
timeout=30
)
response.raise_for_status()
return response.json()</code></pre>
<h4>Error: &quot;Modal authentication failed&quot;</h4>
<pre><code>ERROR: modal.exception.AuthError: Invalid token</code></pre>
<p><strong>Cause</strong>: Missing or expired Modal token</p>
<p><strong>Solution</strong>:</p>
<pre><code class="lang-bash"># Re-authenticate with Modal
modal token set --token-id &lt;YOUR_TOKEN_ID&gt; --token-secret &lt;YOUR_SECRET&gt;
# Or use interactive auth
modal setup</code></pre>
<h3>GPU Errors</h3>
<h4>Error: &quot;GPU not available&quot;</h4>
<pre><code>ERROR: RuntimeError: CUDA is not available</code></pre>
<p><strong>Cause</strong>: GPU not properly configured in decorator</p>
<p><strong>Solution</strong>:</p>
<pre><code class="lang-python"># ❌ Bad: GPU not specified
@app.function()
def train_model():
device = torch.device(&quot;cuda&quot;) # Fails!
model.to(device)
# ✅ Good: Specify GPU
@app.function(gpu=&quot;A10G&quot;)
def train_model():
device = torch.device(&quot;cuda&quot;)
model.to(device)</code></pre>
<h4>Error: &quot;Requested GPU unavailable&quot;</h4>
<pre><code>ERROR: No capacity available for gpu=H100</code></pre>
<p><strong>Cause</strong>: Requested GPU type not available in region</p>
<p><strong>Solution</strong>:</p>
<pre><code class="lang-python"># ❌ Bad: Single GPU type
@app.function(gpu=&quot;H100&quot;) # Might not be available
def train():
pass
# ✅ Good: Use fallback GPUs
@app.function(gpu=&quot;L40S&quot;) # More availability
def train():
pass
# ✅ Better: Use gpu.Any for flexibility
@app.function(gpu=modal.gpu.Any())
def train():
pass</code></pre>
<hr>
<h2>Quick Reference</h2>
<h3>Common Error Messages and Solutions</h3>
<pre><code>Error Pattern | Solution
---------------------------------------|------------------------------------------
ModuleNotFoundError | Add package to image.uv_pip_install()
TimeoutError | Increase timeout parameter
OutOfMemoryError | Increase memory parameter or optimize
CUDA out of memory | Reduce batch size or use larger GPU
ImportError: libXX.so | Add system dependency with apt_install()
NameError: name &#x27;X&#x27; not defined | Move global to function or use class
ConnectionError | Add retry logic and timeouts
AuthError: Invalid token | Run modal setup or modal token set
GPU not available | Add gpu parameter to @app.function()
No capacity for GPU | Use different GPU type or Any()</code></pre>
<h3>Debugging Commands</h3>
<pre><code class="lang-bash"># View real-time logs
modal logs my-app
# Interactive shell in container
modal shell my-app::my_function
# Test locally with dev mode
modal run --dev my_app.py
# Check app status
modal app list
# View function history
modal app logs my-app --function my_function
# Debug image build
modal image build my-app::image --force-rebuild</code></pre>
<h3>Error Prevention Checklist</h3>
<pre><code>✅ DO: Test packages locally before adding to image
✅ DO: Set appropriate timeouts for long-running functions
✅ DO: Monitor memory usage and set limits accordingly
✅ DO: Use retry logic for network calls
✅ DO: Install system dependencies before Python packages
✅ DO: Use modal shell for interactive debugging
❌ DON&#x27;T: Ignore build warnings
❌ DON&#x27;T: Use default timeout for slow operations
❌ DON&#x27;T: Assume global variables work in functions
❌ DON&#x27;T: Skip error handling in production code
❌ DON&#x27;T: Use relative imports
❌ DON&#x27;T: Deploy without testing with --dev first</code></pre>
<hr>
<h2>Anti-Patterns</h2>
<p>❌ <strong>Ignoring logs</strong>: Not checking <code>modal logs</code> when errors occur ✅ Use <code>modal logs my-app</code> to see detailed error traces</p>
<p>❌ <strong>Not using modal shell</strong>: Debugging blind without interactive access ✅ Use <code>modal shell my-app::function</code> to debug interactively</p>
<p>❌ <strong>Skipping --dev mode</strong>: Deploying without local testing ✅ Always test with <code>modal run --dev</code> before deploying</p>
<p>❌ <strong>Generic error handling</strong>: Catching all exceptions without logging ✅ Log specific errors with context for debugging</p>
<p>❌ <strong>Not pinning versions</strong>: Using unpinned package versions ✅ Pin all package versions: <code>uv_pip_install(&quot;pandas==2.1.0&quot;)</code></p>
<p>❌ <strong>Large Docker images</strong>: Installing unnecessary packages ✅ Only install required packages, use debian_slim base</p>
<p>❌ <strong>No timeout strategy</strong>: Using default timeouts everywhere ✅ Set appropriate timeouts per function based on expected runtime</p>
<p>❌ <strong>Ignoring GPU metrics</strong>: Not monitoring GPU utilization ✅ Log GPU memory usage and utilization during runs</p>
<hr>
<h2>Related Skills</h2>
<ul><li><code>modal-performance-debugging.md</code> - Performance profiling and optimization</li><li><code>modal-functions-basics.md</code> - Basic Modal function setup and configuration</li><li><code>modal-gpu-workloads.md</code> - GPU configuration and best practices</li><li><code>modal-image-building.md</code> - Image building strategies and optimization</li><li><code>modal-web-endpoints.md</code> - Debugging web endpoint specific issues</li></ul>
<hr>
<p><strong>Last Updated</strong>: 2025-10-18 <strong>Format Version</strong>: 1.0 (Atomic)</p>
<footer>
<div class="fmap">
<div><b>Build</b>
<a href="https://hanzo.app">hanzo.app</a> app builder
<a href="https://hanzo.codes">hanzo.codes</a> code with an agent
<a href="https://hanzoskills.com">hanzoskills.com</a> what an agent reads</div>
<div><b>Run</b>
<a href="https://console.hanzo.ai">console.hanzo.ai</a> cloud console
<a href="https://api.hanzo.ai">api.hanzo.ai</a> the API</div>
<div><b>Account</b>
<a href="https://hanzo.id">hanzo.id</a> sign in
<a href="https://pay.hanzo.ai">pay.hanzo.ai</a> top up
<a href="https://billing.hanzo.ai">billing.hanzo.ai</a> invoices and usage</div>
<div><b>Company</b>
<a href="https://hanzo.ai">hanzo.ai</a> canonical
<a href="https://hanzo.ventures">hanzo.ventures</a> ventures</div>
</div>
<div class="fend"><a href="/modal-modal-common-errors.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
</footer>
</div></body></html>