Troubleshooting

Most problems here fall into a handful of buckets. Find yours below; if nothing matches, jump to the end.

Installation

command not found: specui

• Use npx @logicplanes/specui@latest <cmd>, or install globally with npm install -g @logicplanes/specui
• Check you're on Node 18+: node -v

Wrong version in CI

Pin explicitly: npx -y @logicplanes/specui@2.0.2 validate …

init

.specui already exists

Use --force only if you genuinely intend to overwrite the contract — it's destructive.

init --dry-run errors on themes

Update the CLI — preset list parsing was fixed in recent releases.

No AGENTS.md block

Re-run with --agents-md. Check validate for agents-md-block-missing.

validate

Missing required component / pattern

SPEC.md lists componentsRequired / patternsRequired from your preset. Either add what's missing:

npx specui add component <name>

or edit the SPEC.md front matter to match what you actually ship, then validate again.

readOrder mismatch

Make sure the readOrder in SPEC.md front matter matches the Schema order, including AGENTS-GUIDE.md.

AGENTS.md block stale

# Refresh block (avoid --force on .specui unless overwriting)
npx specui init --agents-md --target . 

If .specui exists, init refuses to overwrite it — use your team's documented refresh flow, or merge the block from the latest specui templates.

Contrast warnings fail --strict

Fix the offending token pairs in TOKENS.yaml, or adjust the semantic roles in 02-foundations-tokens.md. As a temporary escape hatch there's --no-contrast — but don't leave it in production CI.

Placeholder values in foundations

Replace TODO / template placeholders in the numbered docs and token files.

sync / registry

Link errors after manual edits

npx specui sync

Fix broken paths in manifests, and make sure components/<name>/ exists for every registered id.

registry.json out of date in CI

Add a sync + diff check — see CI/CD.

get / registries

Network / registry fetch failed

• Check outbound HTTPS
• Offline, use specui get --from file:///path/item.json
• specui get --list requires network for shadcn

Component already exists

Use --force on get to replace the vendor tree (review the diff afterwards).

load / link / update

load refuses — .specui exists

Use --force, or unlink / remove .specui first (back it up with export).

update fails validate

Run specui update --name <source> and read the validate JSON; fix the design system or your app overrides. specui diff shows exactly which tokens changed.

push — not a flat SpecUI

push only works when SPEC.md is at the repo root (the specui new layout).

GitHub Wiki sync

Sync Wiki workflow: repository not found / .wiki.git

GitHub only creates the Wiki git backend after you save one page in the UI — until then there is nothing to push to. (The wiki/ folder in this repo is the source; the Wiki tab is a mirror.)

1. Open https://github.com/logicplanes/specui/wiki/_new
2. Title it Home, add any line, Save
3. Re-run Actions → Sync Wiki (or push a change under wiki/ on dev)

The workflow runs node scripts/sync-wiki.mjs (all doc pages + _Sidebar.md). If the push still fails, add the repo secret WIKI_PUSH_TOKEN (a classic PAT with repo scope).

Docs site / links

404 on /specui/specui/docs

Use /specui/docs/ — don't double the GitHub Pages base path. Fixed in site 2.0.2+.

MCP

install-hook wrote config but the editor ignores it

Restart the editor. If it still doesn't pick it up, run specui mcp config and merge the output manually.

HTTP transport not yet implemented

Use the default stdio transport: specui mcp start.

Still stuck?

1. npx specui doctor
2. npx specui validate .specui --json --strict
3. GitHub issues with redacted validate --json output

Next steps

• Validation
• CLI reference
• Scenarios