mirror of
https://github.com/hanzoai/skills.git
synced 2026-11-19 00:47:36 +00:00
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]>
536 lines
27 KiB
HTML
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: "ModuleNotFoundError" at runtime</h4>
|
|
<pre><code>ERROR: ModuleNotFoundError: No module named 'requests'</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("https://api.example.com").json()
|
|
|
|
# ✅ Good: Install package in image
|
|
image = modal.Image.debian_slim().uv_pip_install("requests")
|
|
|
|
@app.function(image=image)
|
|
def fetch_data():
|
|
import requests
|
|
return requests.get("https://api.example.com").json()</code></pre>
|
|
<h4>Error: "Package installation failed"</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(
|
|
"numpy==2.0.0", # Version doesn't exist
|
|
"pandass" # Typo
|
|
)
|
|
|
|
# ✅ Good: Verify versions and names
|
|
image = modal.Image.debian_slim().uv_pip_install(
|
|
"numpy==1.26.0", # Valid version
|
|
"pandas==2.1.0" # Correct spelling
|
|
)</code></pre>
|
|
<p><strong>Debugging tip</strong>: Test packages locally first with <code>uv pip install</code></p>
|
|
<h4>Error: "System dependency missing"</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("opencv-python")
|
|
|
|
# ✅ Good: Install system dependencies first
|
|
image = (
|
|
modal.Image.debian_slim()
|
|
.apt_install("libgl1-mesa-glx", "libglib2.0-0")
|
|
.uv_pip_install("opencv-python")
|
|
)</code></pre>
|
|
<h3>Runtime Errors</h3>
|
|
<h4>Error: "TimeoutError"</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: "OutOfMemoryError"</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("huge_file.csv") # 5GB file
|
|
return df.shape
|
|
|
|
# ✅ Good: Increase memory limit
|
|
@app.function(memory=8192) # 8GB RAM
|
|
def process_large_file():
|
|
df = pd.read_csv("huge_file.csv")
|
|
return df.shape
|
|
|
|
# ✅ Better: Stream data instead
|
|
@app.function(memory=2048)
|
|
def process_large_file_streaming():
|
|
chunks = pd.read_csv("huge_file.csv", chunksize=10000)
|
|
total_rows = sum(len(chunk) for chunk in chunks)
|
|
return total_rows</code></pre>
|
|
<h4>Error: "GPUOutOfMemoryError"</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="A10G") # 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="A10G")
|
|
def train():
|
|
batch_size = 32 # Fits in memory
|
|
train_loader = DataLoader(dataset, batch_size=batch_size)
|
|
|
|
# ✅ Better: Use gradient accumulation
|
|
@app.function(gpu="A10G")
|
|
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: "Relative import error"</h4>
|
|
<pre><code>ERROR: ImportError: attempted relative import with no known parent package</code></pre>
|
|
<p><strong>Cause</strong>: Relative imports don't work in Modal'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 "helper"
|
|
|
|
@app.function()
|
|
def main():
|
|
result = helper_function.remote()
|
|
|
|
# Option 2: Use Modal's mount feature
|
|
from modal import Mount
|
|
|
|
@app.function(
|
|
mounts=[Mount.from_local_dir("./src", remote_path="/root/src")]
|
|
)
|
|
def main():
|
|
import sys
|
|
sys.path.append("/root/src")
|
|
from utils import helper_function</code></pre>
|
|
<h4>Error: "NameError: name 'X' is not defined"</h4>
|
|
<pre><code>ERROR: NameError: name 'MY_CONSTANT' 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: "ConnectionError: Failed to connect"</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("https://api.example.com/data")
|
|
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(
|
|
"https://api.example.com/data",
|
|
timeout=30
|
|
)
|
|
response.raise_for_status()
|
|
return response.json()</code></pre>
|
|
<h4>Error: "Modal authentication failed"</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 <YOUR_TOKEN_ID> --token-secret <YOUR_SECRET>
|
|
|
|
# Or use interactive auth
|
|
modal setup</code></pre>
|
|
<h3>GPU Errors</h3>
|
|
<h4>Error: "GPU not available"</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("cuda") # Fails!
|
|
model.to(device)
|
|
|
|
# ✅ Good: Specify GPU
|
|
@app.function(gpu="A10G")
|
|
def train_model():
|
|
device = torch.device("cuda")
|
|
model.to(device)</code></pre>
|
|
<h4>Error: "Requested GPU unavailable"</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="H100") # Might not be available
|
|
def train():
|
|
pass
|
|
|
|
# ✅ Good: Use fallback GPUs
|
|
@app.function(gpu="L40S") # 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 'X' 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'T: Ignore build warnings
|
|
❌ DON'T: Use default timeout for slow operations
|
|
❌ DON'T: Assume global variables work in functions
|
|
❌ DON'T: Skip error handling in production code
|
|
❌ DON'T: Use relative imports
|
|
❌ DON'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("pandas==2.1.0")</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> |