design-agent-troubleshoot

$npx mdskill add langchain-ai/design-agent/design-agent-troubleshoot

Report missing settings by name and never paste a key, token or `.env` line.

SKILL.md

.github/skills/design-agent-troubleshootView on GitHub ↗
---
name: design-agent-troubleshoot
description: Diagnose Design Agent when something fails. Setup, a render, a deploy, Slack or a model call. Run doctor and the connection tests, read logs and traces, match the symptom to its fix, and never print credentials. Use when a command errors, a reply never comes, or a file looks wrong.
---

# Troubleshoot Design Agent

Report missing settings by name and never paste a key, token or `.env` line.

1. `uv run design-agent doctor` (add `--json` to parse it) checks every model role, keys, the brand,
   the sandbox, MDA declarations, MCP and Paper. Fix what it names first.
2. Real calls, a few cents each: `uv run design-agent test model`, `test sandbox`, `test paper`,
   `test slack`, `test db`.
3. Match the symptom:

| Symptom | Fix |
| --- | --- |
| `demo` needs a sandbox | start Docker, then `uv run design-agent sandbox build` |
| A render is missing a font | `uv run design-agent fonts verify`; `family` in `fonts.toml` must be the name inside the file |
| Off-brand colours or a failed brand check | `uv run design-agent brand validate`, then `brand css` |
| "The connection to the model stalled" or "stayed unavailable" | check the provider's status, then reply `continue` in the thread |
| Background news arrives a minute or two late on MDA | expected: MDA schedules land on the next minute |
| "A restart may have stopped…" | a deploy or restart stopped helpers; ask the agent to resume them |
| Paper "not connected" | Paper Desktop is closed or the bridge is down; boards still render in the sandbox |
| The sandbox bake runs out of disk on `mda deploy` | `uv run design-agent sandbox publish` first |
| "Context Hub only accepts UTF-8 text files" | move the skill's binary files to `skill-binaries/<skill>/` |
| "source archive … exceeds the 200 MB limit" | clear old renders in `workspace/out/` |
| An MCP server is missing | the startup log names the one that failed; the rest keep working |

4. **Logs:** `uv run mda logs` on MDA; `docker compose -f deploy/self-host/compose.yaml logs api`
   when self-hosted. Logs carry exception classes, never provider messages or keys.
5. **Traces:** every run is traced in LangSmith (an MDA deployment's project is
   `<deployment>-production`). Follow a bad file back to the skills read, tools called and checks
   run, with the [langsmith-trace](../langsmith-trace/SKILL.md) skill. API runs attach delivered
   files to the trace. The deployed agent can read its own traces too (`list_traces`,
   `read_trace`): ask it in the thread what went wrong.
6. **A real bug:** reproduce it with a failing test before changing code, then follow `AGENTS.md`.

More: [Operations](../../../OPERATIONS.md).

More from langchain-ai/design-agent

SkillDescription
brand-onboardingBuild the active brand pack in workspace/brand/ from a brand guide, website, files or a Paper file, validate it, and have a person review it.
data-vizCharts, stat cards, flywheels and diagrams (flows, architectures, hierarchies) rendered on brand from a JSON spec to PNG and SVG. Use for any visual whose job is numbers or relationships, including restyling an attached chart or diagram.
design-agent-customizeChange what Design Agent knows and does. Teach it a new deliverable with a runtime skill, change its instructions, design doctrine or checks, connect MCP servers and tools, or change models and cost caps. Use when someone wants it to make something new, follow a new rule, or use another tool.
design-agent-deployPut Design Agent in a team's Slack. Deploy it to Managed Deep Agents (one command, managed Slack app) or self-host it with Docker Compose, verify it with a real request, ship updates, and keep a separate test copy. Use when someone wants the agent running for their team.
design-agent-evalsFind out whether a change made Design Agent better or worse. Run the eval set or a few tasks before and after against the same model, read the reports, look at the files, and turn a real request that went wrong into a task. Use after changing instructions, skills, checks or models, or when someone asks how good it is.
design-agent-onboardingInstall and configure Design Agent, add a brand, connect Paper, choose MDA or self-hosting, and diagnose setup without exposing credentials.
design-agent-updateBring a fork or clone of Design Agent up to date with the upstream repository while keeping the team's brand, skills and edits, rebuild what changed, and redeploy safely. Use when someone asks to update, upgrade or pull the latest Design Agent.
design-wikiDesign doctrine to weigh on any visual. Hierarchy, typography, colour, layout, platform sizes, chart and diagram principles, and the review rubric critics score against.
embedded-captions>
faceless-explainerTurn arbitrary text — an article, notes, a topic, a brief — into a faceless explainer video: there is no site or footage to capture, so the visuals are invented per scene (typography, abstract graphics, diagrams, data-viz). Use for topic explainers, concept breakdowns, how-tos, listicles. Not a video built from a website (/product-launch-video — promo or tour). Unclear → /hyperframes.