troubleshoot-print-issues
About
This skill diagnoses and fixes common 3D printing failures through systematic symptom analysis. It covers issues like adhesion problems, stringing, layer shifts, and extrusion errors for both FDM and SLA printers. Use it when prints fail mid-process, exhibit quality defects, or when new materials or hardware cause inconsistent results.
Quick Install
Claude Code
Recommendednpx skills add pjt222/agent-almanac -a claude-code/plugin add https://github.com/pjt222/agent-almanacgit clone https://github.com/pjt222/agent-almanac.git ~/.claude/skills/troubleshoot-print-issuesCopy and paste this command in Claude Code to install this skill
Documentation
排印之疾
以系統之症析診而修 3D 印之常敗。此術涵 FDM 與 SLA 之最常見之疾:床附不良、拉絲、層偏、翹曲、出料不足、出料過剩、印品之缺。其法在辨症、究本、迭修。
用時
- 印於首層或中途敗
- 印成而有缺(拉絲、塊、隙、面粗)
- 度量有訛(過大過小、翹曲、象足)
- 層附之疾(裂、分)
- 支柱毀印或印中支敗
- 印與切片預覽異
- 材於各印中表異
- 新材、新機、或新環致疾
入
- failure_description:何敗(首層敗、拉絲、翹曲等)
- failure_timing:敗於何時(首層、中途、特定高、頂層)
- material:絲/脂之類、牌、齡、藏狀
- printer:機型、嘴徑、床質、罩否
- recent_changes:新材、切片設、機改、境
- print_history:此模常通乎?此材昔可乎?
法
第一步:聚敗之症
詳記可察之症:
目察:
- 攝其敗(總、近、特定缺)
- 記敗位(首層、特定高、頂面)
- 述缺類:隙、塊、絲、偏、裂
境之數:
- 印時之溫
- 濕度
- 風或冷氣襲機
- 時辰(溫變)
印之參:
# Extract from G-code metadata
grep "^;MAXX\|^;MINX\|^;MAXZ" failed_print.gcode # Print dimensions
grep "^;PRINT_TIME:" failed_print.gcode # Estimated time
grep "^M104\|^M140" failed_print.gcode | head -5 # Temperatures
grep "^;generated by" failed_print.gcode # Slicer version
得:症詳述、有圖、有參、有境。
敗則:症不明者,印一校驗(溫塔、拉絲試、benchy)以系察其敗。
第二步:依症類其疾
合所察之症於常敗之模:
診斷參表
| 症 | 可能之因 | 速查 | 優先修 |
|---|---|---|---|
| 床附不良 | 床污、溫誤、Z 過高 | 拭床、平床 | 清床、Z-offset 下調 0.05mm |
| 拉絲 | 過熱、回抽不足 | 察嘴溫 | 降溫 5°C、增回抽 +0.5mm |
| 層偏 | 帶鬆、過速、相撞 | 察帶之張 | 緊帶、減速 20% |
| 翹曲 | 附差、冷急 | 察角之翹 | 加 brim、罩機、增床溫 |
| 出料不足 | 堵、溫低、流誤 | 察出料一致否 | 清嘴、增溫 5°C、校 e-steps |
| 出料過剩 | 流高、e-steps 誤 | 察塊形 | 減流 2-5%、校 e-steps |
| 象足 | 首層擠、床過熱 | 量基寬 | 升 Z-offset +0.05mm、降床溫 5°C |
| 壁有隙 | 壁薄、出不足 | 察壁厚 | 啟薄壁察、增流 |
| 層分 | 溫低、冷劣、污 | 察層紋 | 增溫 5-10°C、察濕絲 |
| 塊/瘡 | 回抽、coast 設 | 察縫對齊 | 調回抽、啟 coasting |
| 頂面粗 | 頂層少、熨之 | 數實頂層 | 加 2 頂層、啟 ironing |
| 懸垂下垂 | 冷少、過熱 | 察件冷扇 | 增冷、降溫、加支 |
得:敗已歸 1-3 最可能之類。
敗則:症合多類者,依敗時為先(首層先、中途次、頂面後)。
第三步:行根因之析
究其本,勿止於症:
5 Why 之術:
Symptom: Print warping and lifting from bed
Why? → Poor bed adhesion in corners
Why? → Corners cooling faster than center
Why? → Room draft from AC vent
Why? → No enclosure to maintain stable temperature
Why? → ABS requires heated chamber for uniform cooling
Root cause: Material choice (ABS) incompatible with open printer in drafty room
常見根因之類:
機械:
- 帶、輪、止轉螺鬆
- 直線軸承或桿磨/污
- Z 軸卡或不正
- 擠輪磨或滑
熱:
- 溫感漂或敗
- 熱床力/隔不足
- 件冷不足
- 境溫變
材:
- 濕絲(吸水之材)
- 老/變之材
- 污絲(塵、油)
- 材與用不合
設:
- e-steps 校誤
- 流率乘誤
- 切片有訛或側檔誤
- 韌之加速/jerk 過高
得:根因明,有證(量溫、帶張、目察)。
敗則:根因不明者,用排除之法:修最可能之因,再試,反覆至解。
第四步:施初級之修
行常見之疾之即解:
床附不良
即修:
# 1. Clean bed thoroughly
# Glass/PEI: Isopropyl alcohol 90%+
# BuildTak: Warm water and dish soap
# 2. Level bed (paper test at 4 corners + center)
# Paper should drag slightly
# 3. Adjust Z-offset down (squish first layer more)
# Start: -0.05mm increments until lines fuse
# 4. Increase bed temperature +5°C
# 5. Add adhesion aid:
# - Glue stick (PLA/PETG)
# - Hairspray (ABS)
# - ABS juice (ABS) - ABS dissolved in acetone
# - Magigoo/3D printing adhesive
切片設:
- 首層高:0.2-0.3mm(厚則擠佳)
- 首層速:20mm/s(緩則附佳)
- 加 brim:8-10mm 為小底之件
- 加 raft:為極難之材(TPU、Nylon)
得:首層全附,無翹。
敗則:以隙規或網平察床平度;床翹者需玻/PEI 板或網補。
拉絲
先溫之法:
1. Print temperature tower (180-220°C in 5° steps for PLA)
2. Identify lowest temperature that extrudes cleanly
3. Use that temperature -5°C to minimize stringing
回抽之調:
# Direct drive extruder:
retraction_distance: 1.0-2.0mm
retraction_speed: 40-50mm/s
# Bowden extruder:
retraction_distance: 4.0-6.0mm
retraction_speed: 40-60mm/s
# If stringing persists:
- Enable z-hop: 0.2-0.4mm (lifts nozzle during travel)
- Reduce travel speed (paradoxically helps)
- Enable combing mode (travels within infill)
得:拉絲微,細絲手可除。
敗則:察嘴半堵或濕絲(皆致溢)。
層偏
機械之察:
# 1. Check belt tension (should twang like guitar string)
# Tighten if loose
# 2. Check pulley set screws (motor shafts)
# Must align with flat on motor shaft
# 3. Check for mechanical resistance
# Manually move X/Y axes - should glide smoothly
# Binding indicates dirty rods, worn bearings, or misalignment
# 4. Check stepper motor current (advanced)
# Too low → skipping; too high → overheating
減速:
# Reduce these speeds:
perimeter_speed: 40mm/s (from 50)
travel_speed: 120mm/s (from 150)
acceleration: 500mm/s² (from 1000)
jerk: 8mm/s (from 15)
得:再印時,緊帶減速之後,無層偏。
敗則:察切片所生之撞(件冷扇撞模)或電之疾(步進驅過熱)。
翹曲
熱之治:
# Increase bed temperature:
PLA: 60°C → 65°C
PETG: 80°C → 85°C
ABS: 100°C → 110°C
# Disable/reduce part cooling:
first_layer_fan: 0%
regular_fan: 25% max (ABS), 50% (PETG), 100% (PLA)
# Enclose printer (critical for ABS/ASA):
- Cardboard box (temporary)
- Acrylic panels (permanent)
- Target chamber temp: 40-50°C
附之強化:
- 加 brim:10-15mm 為角
- 加「鼠耳」:15mm 徑之圓於利角
- 模底之邊倒角(45° × 1mm 除應力集中)
得:件平而無角翹。
敗則:材與機本不合(ABS 於無罩之機)——換 PETG 或 ASA。
出料不足
速修:
# 1. Check for nozzle clog
# Heat to print temp, manually push filament
# Should extrude smoothly
# 2. Cold pull cleaning (if partial clog)
# Heat to 220°C, push cleaning filament through
# Cool to 90°C, pull sharply - should remove debris
# 3. Increase temperature +5-10°C
# Higher temp = better flow
# 4. Increase flow rate 2-5%
# Slicer: Filament settings → Flow → 102-105%
E-steps 校:
# 1. Mark filament 120mm above extruder
# 2. Extrude 100mm: G1 E100 F100
# 3. Measure remaining distance to mark
# 4. Calculate: new_steps = current_steps × (100 / actual_extruded)
# 5. Set: M92 E<new_steps>; M500 (save to EEPROM)
得:出料一致,周或填無隙。
敗則:察熱蠕(冷扇敗)、擠輪磨、或擠臂裂。
出料過剩
減流:
# Reduce flow in 2% increments:
extrusion_multiplier: 0.98 → 0.96 → 0.94
# Signs of correct flow:
- Smooth top surface (not overstuffed)
- Perimeters don't bulge outward
- Infill doesn't overfill and push layers apart
度量校:
# Print 20mm calibration cube
# Measure with calipers:
# X/Y dimensions should be 20.0mm ± 0.1mm
# If consistently oversized → reduce flow
# If undersized → increase flow
得:度量正、面滑、無凸。
敗則:再校 e-steps(或設過高)。
第五步:以試印驗修
行全印之前,確其解:
試印之擇:
- 附之疾:20mm 方 × 5 層(速首層試)
- 拉絲:拉絲試模(雙塔有距)
- 層偏:高瘦之試(壓機械系)
- 翹曲:大平面(200mm × 200mm × 0.4mm)
- 出料:20mm 校立方(度量正)
得:試印成,疾解。
敗則:試敗者,疾未全解或多疾並存——再診,專注餘症。
第六步:記其解
錄成之修以備後用:
疾之記模:
date: 2026-02-16
issue: "Layer shifts at 50mm height"
symptoms: "X-axis shifts 10mm, happens consistently at same height"
printer: "Ender 3 V2"
material: "PETG, PolyMaker PolyLite"
root_cause: "Loose X-axis belt, pulley set screw not on flat"
solution:
- "Tightened X-axis belt to 120Hz resonance"
- "Realigned pulley set screw on motor shaft flat"
- "Reduced print speed to 40mm/s perimeter"
verification: "Printed 100mm test cylinder - no shifts"
notes: "Check belt tension monthly, pulley tends to slip"
得:疾已記,根因與解皆入庫。
敗則:雖未成之嘗試亦宜記,免重蹈敗解。
驗
- 敗症已記,有圖有具察
- 疾以參表分類
- 根因明(機、熱、材、設)
- 依根因類施合修
- 全印之前以試印驗修
- 解已入記,含日、因、解
- 境因已錄(溫、濕、風)
- 材狀已察(乾、無污、藏正)
陷
- 多變並改:每次調一參;否則不知何修之(或何敗之)
- 忽濕絲:吸水之材(Nylon、TPU、PETG)受濕致泡、絲、附差——常先疑濕絲
- 略機械之察:帶鬆、件磨之疾,切片無論何調皆不能修
- 取網之溫:每機材之合皆異——必自行溫塔
- 帶過緊:過緊則軸承早磨;目標如琴弦,非鋼索
- 罪切片:切片之訛少;95% 之疾屬機、熱、材
- 不清嘴:半堵致斷續出料不足,似流或 e-step 之疾
- 假床平:床久而翹、簧壓、調滑——每週重平以保穩
- Z-offset 誤:首層之敗多為 Z-offset 過高(擠不足)或過低(嘴刮床)
- 境之忽:ABS/ASA 於 15°C 風車庫永不能良印——材需穩暖之境
參
- prepare-print-model:確模備正以免印之疾
- select-print-material:擇與機與境合之材
- 校 3D 印機(後出之術):E-steps、流率、溫塔、PID 調、床網平
- 守 3D 印機(後出之術):帶張、軸承潤、嘴換、預修
GitHub Repository
Related Skills
executing-plans
DesignUse the executing-plans skill when you have a complete implementation plan to execute in controlled batches with review checkpoints. It loads and critically reviews the plan, then executes tasks in small batches (default 3 tasks) while reporting progress between each batch for architect review. This ensures systematic implementation with built-in quality control checkpoints.
requesting-code-review
DesignThis skill dispatches a code-reviewer subagent to analyze code changes against requirements before proceeding. It should be used after completing tasks, implementing major features, or before merging to main. The review helps catch issues early by comparing the current implementation with the original plan.
connect-mcp-server
DesignThis skill provides a comprehensive guide for developers to connect MCP servers to Claude Code using HTTP, stdio, or SSE transports. It covers installation, configuration, authentication, and security for integrating external services like GitHub, Notion, and custom APIs. Use it when setting up MCP integrations, configuring external tools, or working with Claude's Model Context Protocol.
web-cli-teleport
DesignThis skill helps developers choose between Claude Code Web and CLI interfaces based on task analysis, then enables seamless session teleportation between these environments. It optimizes workflow by managing session state and context when switching between web, CLI, or mobile. Use it for complex projects requiring different tools at various stages.
