Back to Skills

troubleshoot-print-issues

pjt222
Updated 2 days ago
7 views
17
2
17
View on GitHub
Designai

About

This Claude Skill diagnoses and fixes common 3D printing failures like adhesion problems, stringing, and warping through systematic symptom analysis. Use it when prints fail mid-process, exhibit quality defects, or after hardware/material changes. It provides actionable troubleshooting steps for developers integrating print issue resolution.

Quick Install

Claude Code

Recommended
Primary
npx skills add pjt222/agent-almanac -a claude-code
Plugin CommandAlternative
/plugin add https://github.com/pjt222/agent-almanac
Git CloneAlternative
git clone https://github.com/pjt222/agent-almanac.git ~/.claude/skills/troubleshoot-print-issues

Copy and paste this command in Claude Code to install this skill

Documentation

3Dプリント問題のトラブルシューティング

Diagnose and fix common 3D printing failures using systematic symptom analysis. This skill covers the most frequent FDM and SLA issues: poor bed adhesion, stringing, layer shifts, warping, under-extrusion, over-extrusion, and print quality defects. Uses a structured approach of symptom identification, root cause analysis, and iterative fixes.

使用タイミング

  • Print fails during first layer or partway through
  • Finished prints have quality defects (stringing, blobs, gaps, rough surfaces)
  • Dimensional accuracy problems (over/undersized, warping, elephant foot)
  • Layer adhesion issues (delamination, splitting)
  • Support removal leaves damage or supports fail during print
  • Prints look different from slicer preview
  • Material behaves inconsistently across prints
  • New material, printer, or environmental conditions causing issues

入力

  • failure_description: What went wrong (failed first layer, stringing, warping, etc.)
  • failure_timing: When issue occurs (first layer, midprint, specific height, top layers)
  • material: Filament/resin type, brand, age, storage conditions
  • printer: Make/model, nozzle size, bed type, enclosure
  • recent_changes: New material, slicer settings, hardware modifications, environment
  • print_history: Does this model usually work? Did this material work before?

手順

1. Collect Failure Symptoms

Document observable symptoms with specificity:

Visual inspection:

  • Take photos of failure (overall, close-up, specific defect)
  • Note failure location (first layer, specific height, top surface)
  • Describe defect type: gaps, blobs, strings, shifts, cracks

Environmental data:

  • Ambient temperature during print
  • Humidity level
  • Drafts or AC affecting printer
  • Time of day (temperature changes)

Print parameters:

# 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

期待結果: Detailed symptom description with photos, parameters, and environmental context.

失敗時: If symptoms unclear, print a calibration test (temperature tower, stringing test, or benchy) to reproduce and observe failure systematically.

2. Classify Issue by Symptom Pattern

Match observed symptoms to common failure modes:

Diagnostic Reference Table

SymptomLikely CausesQuick CheckPriority Fix
Poor bed adhesionDirty bed, wrong temp, too high ZWipe bed, level bedClean bed, adjust Z-offset down 0.05mm
StringingToo hot, insufficient retractionCheck nozzle tempLower temp 5°C, increase retraction +0.5mm
Layer shiftsLoose belts, too fast, collisionCheck belt tensionTighten belts, reduce speed 20%
WarpingPoor adhesion, fast coolingCheck corners liftingAdd brim, enclose printer, increase bed temp
Under-extrusionClog, low temp, wrong flowCheck extrusion consistencyClean nozzle, increase temp 5°C, calibrate e-steps
Over-extrusionHigh flow rate, wrong e-stepsCheck blob formationReduce flow 2-5%, calibrate e-steps
Elephant footFirst layer squish, bed too hotMeasure base widthRaise Z-offset +0.05mm, lower bed temp 5°C
Gaps in wallsThin walls, under-extrusionCheck wall thicknessEnable thin wall detection, increase flow
Layer delaminationLow temp, poor cooling, contaminationCheck layer linesIncrease temp 5-10°C, check wet filament
Blobs/zitsRetraction, coast settingsCheck seam alignmentTune retraction, enable coasting
Rough top surfaceInsufficient top layers, ironingCount solid top layersAdd 2 top layers, enable ironing
Sagging overhangsInsufficient cooling, too hotCheck part cooling fanIncrease cooling, lower temp, add supports

期待結果: Failure classified into 1-3 most likely categories.

失敗時: If symptoms match multiple categories, prioritize based on failure timing (first layer issues first, then midprint, then top surface).

3. Perform Root Cause Analysis

Investigate underlying cause, not just symptoms:

5 Whys technique:

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

Common root causes by category:

Mechanical:

  • Loose belts, pulleys, or set screws
  • Worn/dirty linear bearings or rods
  • Z-axis binding or misalignment
  • Extruder gear worn or skipping

Thermal:

  • Temperature sensor drift or failure
  • Inadequate heated bed power/insulation
  • Insufficient part cooling
  • Environmental temperature swings

Material:

  • Wet filament (hygroscopic materials)
  • Old/degraded material
  • Contaminated filament (dust, oils)
  • Wrong material for application

Configuration:

  • Incorrect e-steps calibration
  • Wrong flow rate multiplier
  • Slicer bug or wrong profile
  • Firmware acceleration/jerk too high

期待結果: Root cause identified with supporting evidence (measured temperatures, belt tension, visual inspection).

失敗時: If root cause unclear, use elimination method: fix most likely cause, re-test, repeat until resolved.

4. Apply First-Level Fixes

Implement immediate solutions for common issues:

Poor Bed Adhesion

Immediate fixes:

# 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

Slicer settings:

  • First layer height: 0.2-0.3mm (thicker = better squish)
  • First layer speed: 20mm/s (slower = better adhesion)
  • Add brim: 8-10mm for small footprint parts
  • Add raft: For very difficult materials (TPU, Nylon)

期待結果: First layer adheres completely with no lifting.

失敗時: Check bed flatness with feeler gauge or mesh leveling; warped bed requires glass/PEI sheet or mesh compensation.

Stringing

Temperature-first approach:

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

Retraction tuning:

# 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)

期待結果: Minimal stringing, thin strings easily removed by hand.

失敗時: Check for nozzle partial clog or wet filament (both cause oozing).

Layer Shifts

Mechanical checks:

# 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

Speed reduction:

# 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)

期待結果: No layer shifts in re-print with tightened belts and reduced speeds.

失敗時: Check for slicer-generated collisions (part cooling fan hitting model) or electrical issues (stepper driver overheating).

Warping

Thermal management:

# 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

Adhesion enhancement:

  • Add brim: 10-15mm for corners
  • Add "mouse ears": 15mm diameter discs at sharp corners
  • Chamfer bottom edges in model (45° × 1mm removes stress concentrator)

期待結果: Part stays flat with no corner lifting.

失敗時: Material fundamentally unsuitable for printer (ABS on unenclosed printer)—switch to PETG or ASA.

Under-Extrusion

Quick fixes:

# 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 calibration:

# 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)

期待結果: Consistent extrusion with no gaps in perimeters or infill.

失敗時: Check for heat creep (cooling fan failure), worn extruder gear, or cracked extruder arm.

Over-Extrusion

Flow rate reduction:

# 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

Dimensional accuracy test:

# 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

期待結果: Accurate dimensions, smooth surfaces, no bulging.

失敗時: Re-calibrate e-steps (may be set too high).

5. Verify Fix with Test Print

Confirm resolution before attempting full print:

Test print selection:

  • Adhesion issues: 20mm square × 5 layers (fast first layer test)
  • Stringing: Stringing test model (dual towers with travels)
  • Layer shifts: Tall thin test (stress mechanical system)
  • Warping: Large flat surface (200mm × 200mm × 0.4mm)
  • Extrusion: 20mm calibration cube (dimensional accuracy)

期待結果: Test print succeeds with issue resolved.

失敗時: If test fails, issue not fully resolved or multiple issues present—repeat diagnosis focusing on remaining symptoms.

6. Document Solution

Record successful fix for future reference:

Issue log template:

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"

期待結果: Issue documented with root cause and solution for knowledge base.

失敗時: Even unsuccessful troubleshooting attempts should be logged to avoid repeating failed solutions.

バリデーション Checklist

  • Failure symptoms documented with photos and specific observations
  • Issue classified using diagnostic reference table
  • Root cause identified (mechanical, thermal, material, or configuration)
  • Appropriate fix applied based on root cause category
  • Fix verified with test print before attempting full print
  • Solution documented in issue log with date, cause, and resolution
  • Environmental factors recorded (temperature, humidity, drafts)
  • Material condition checked (dry, contamination-free, stored properly)

よくある落とし穴

  1. Changing multiple variables: Adjust one parameter at a time; otherwise you won't know what fixed it (or made it worse)
  2. Ignoring wet filament: Hygroscopic materials (Nylon, TPU, PETG) absorb moisture causing bubbling, stringing, poor adhesion—always suspect wet filament first
  3. Skipping mechanical checks: Loose belts and worn components cause issues no amount of slicer tuning can fix
  4. Temperature from internet: Every printer/material combination is unique—always run your own temperature tower
  5. Over-tightening belts: Too tight = premature bearing wear; aim for guitar string tension, not steel cable
  6. Blaming slicer: Slicer bugs are rare; 95% of issues are mechanical, thermal, or material-related
  7. Not cleaning nozzle: Partial clogs cause intermittent under-extrusion that looks like flow/e-step issues
  8. Assuming bed is level: Beds warp over time, springs compress, and adjustments slip—re-level weekly for reliable results
  9. Wrong Z-offset: Most first layer failures are Z-offset too high (not enough squish) or too low (nozzle scraping bed)
  10. Environmental neglect: ABS/ASA in 15°C garage with drafts will never print well—material requires stable warm environment

関連スキル

  • prepare-print-model: Ensure model is properly prepared to avoid printability issues
  • select-print-material: Choose material appropriate for printer capabilities and environment
  • Calibrate 3D Printer (future skill): E-steps, flow rate, temperature towers, PID tuning, and bed mesh leveling
  • Maintain 3D Printer (future skill): Belt tensioning, bearing lubrication, nozzle replacement, and preventive maintenance

GitHub Repository

pjt222/agent-almanac
Path: i18n/ja/skills/troubleshoot-print-issues
0
agentsagentskillsai-assisted-developmentclaude-codeskillsteams

Related Skills

executing-plans

Design

Use 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.

View skill

requesting-code-review

Design

This 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.

View skill

connect-mcp-server

Design

This 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.

View skill

web-cli-teleport

Design

This 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.

View skill