Troubleshooting

Find your symptom. Install problems first, output quality after.

It won't install

EBADENGINE on pnpm install

Wrong Node major. OpenDesign needs Node 24; Node 22 isn't supported.

nvm install 24 && nvm use 24
node -v   # expect v24.x
corepack enable

better-sqlite3 hangs on Windows

Known on Node 24. Install Visual Studio Build Tools (with the C++ desktop workload), then rerun pnpm install.

Three alternatives, easiest first:

1. Use the Windows installer and skip source entirely.
2. Run the source build inside WSL.
3. Install Build Tools and retry.

Wrong pnpm version

Use Corepack rather than a global install:

corepack enable
# pnpm then follows the lockfile pin, 10.33.2

Port already in use

The previous run didn't stop:

pnpm tools-dev stop

Still stuck? Move the ports:

pnpm tools-dev --daemon-port 27456 --web-port 27573

Don't hardcode ports in scripts.

You don't know what's missing

pnpm tools-dev check

Faster than reading logs. It prints exactly what the environment lacks.

The agent won't connect

No agent appears in the UI

In this order:

1. Is the CLI on your PATH? Type its name in a terminal (claude, codex, cursor-agent…) and see if it starts.
2. Is it signed in? Get the CLI working on its own first.
3. Using an API key? Is .od/media-config.json correct?
4. Run pnpm tools-dev check.

Permission prompts keep looping

The environment is incomplete. pnpm tools-dev check names the missing piece.

Generation sits on "waiting"

• Check whether that agent still has quota.
• Check that your machine can reach the provider.
• Try a different agent — that tells you whether it's OpenDesign or the agent.

A skill stopped working after switching agents

Skills themselves are agent-agnostic, so this is usually a capability difference — the new agent may not browse or generate images. Check what the skill depends on.

The output is wrong

It's images; the text can't be selected

Some agents take the shortcut of slicing the reference into the HTML. Add:

All text must be real text nodes, selectable and editable. Text must
never be rendered as an image.

The style ignored the reference

Two causes:

1. The reference never arrived. Confirm the attachment.
2. Your description was too vague. Name the specifics — the palette bias, the type personality, the texture, how open the whitespace is.

Content got trimmed

Name the slide. Don't say "some content is missing".

Slide 5 is down to its title. Restore the full content from the plan,
with layout consistent with slides 4 and 6.

Fixing one thing broke another

Refine in narrow passes and add:

Change only what I listed. Leave everything else alone.

Every pass gets busier

State the priority:

Priority: readability > information hierarchy > visual impact.
When they conflict, sacrifice visual impact.

The numbers are invented

Write it into the prompt:

Any number without a real source becomes a clearly labelled
placeholder. Do not estimate and do not invent. List which numbers you
need from me.

For something already generated, make it account for itself:

List every number on the page and state its source. Anything you
generated without a source, mark as unverified.

The states aren't covered

The most common AI-design failure. Ask directly:

Bring this up to state coverage: empty, loading, error, single item,
heavy data. The error state says how to recover; the empty state
offers a next step.

It reads as AI-made

Run the anti-slop self-check. The usual ingredients: purple gradients, generic icons, a defaulted three-column layout, invented user counts, uniform density.

Export

The PPTX lost a lot

Expected. Three.js scenes, JS-dependent interaction, and advanced CSS don't survive.

If the deliverable must be a .pptx, work backwards: do less at the motion step, skip 3D, and spend the effort on layout and charts.

Charts are blurry in the PDF

Require vectors:

Render charts as SVG for PDF export, not bitmaps.

The inline HTML is too big to email

Images are base64-embedded. Either compress them first, or switch to linked assets and ship a ZIP.

A dark deck exports as a black slab

Print usually wants a light variant:

Before exporting to PDF, produce a print version: light background,
dark text, no background motion or decorative gradients, and charts
on a light ground.

In the room

Dropped frames on the projector

Three.js scenes frequently fail through a projector or a screen share. Test on the real machine and screen before you present. If it can't hold, switch to CSS animation.

The type is too small projected

Sizes that look right in a browser often fail on a large screen from the back row. Preview full screen and step back to that distance.

Motion turns to mush over a screen share

Video encoding destroys fine motion. For remote sessions, cut motion to a minimum or present the PDF.

It won't open at the venue

Always export a PDF backup. Not because OpenDesign is unreliable — because the venue's laptop, adapters, and network aren't yours.

Still stuck

• pnpm tools-dev check is the fastest first-hand information.
• Search GitHub Issues for the same symptom.
• Ask on Discord.
• The official quickstart carries a short troubleshooting list: open-design.ai/quickstart.