Automation

Troubleshooting

Common warnings, error codes, and fallbacks when your AI assistant can't reach the Artimic MCP server or produces a broken design.

The MCP server returns structured errors and warnings on every call. Your assistant should self-correct from them automatically. This page is for the moments when it doesn't — or when the connection itself isn't working.

#Connection problems

#"Server not connected" / `artimic` shows red in `/mcp`

Check the URL. The endpoint is https://artimic.com/api/mcp — note the /api/mcp path. https://artimic.com alone won't work.
Test it from a terminal:
```
curl -s https://artimic.com/api/mcp/capabilities | head -c 200
```
Expected: a JSON blob starting with {"schemaVersion":2,…. If you get HTML or a 404, the server is down or you typed the URL wrong.
Restart your AI client. Most clients only re-read MCP config on startup.

#"Method not found" / "Not Acceptable"

If you're sending JSON-RPC by hand (e.g. curl), you need the correct Accept header:

curl -X POST https://artimic.com/api/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

The text/event-stream half is required by the streamable-HTTP transport. Most MCP clients add it automatically.

#Design problems

#The render returned bytes but the design looks wrong / invisible

Inspect the warnings array in the response. Every compile/render call returns one. The most common warnings:

Code	Meaning	Fix
`coords.fractional_suspected`	Your assistant passed `0..1` fractions instead of pixels	Re-prompt: "Use pixel coordinates, not 0..1 fractions."
`layer.off_canvas`	A layer is entirely outside the canvas	Re-prompt with a smaller canvas or layers inside its bounds
`font.unknown_family`	A font fell back to system-ui because the requested family isn't bundled	Re-prompt with a font from the catalog (Inter, Anton, Bebas Neue, Playfair Display, JetBrains Mono, Pacifico, …)
`opacity.percent_assumed`	Opacity > 1 was treated as a percentage (50 → 0.5)	Use `0..1` opacity values
`gradient.position_clamped`	Gradient stop position was outside `0..1` and got clamped	Use positions in `[0, 1]`
`document.no_content_layers`	Intent had zero content layers — only the background renders	Re-prompt with at least one text/shape/icon layer

#Render returned an error (no bytes)

Look at the errors array. Common error codes:

Code	Meaning
`canvas.required`	No `canvas` field in the intent
`canvas.unknown_preset`	`presetId` doesn't match any known preset
`canvas.dimensions_required`	No preset and no explicit `width` + `height`
`text.width_required`	Text layer was missing the required `width`
`text.font_size_invalid`	`fontSize` was zero or negative
`enum.unknown_blend_mode`	Unknown `blendMode` (catalog has 12 valid values)
`enum.unknown_shape_type`	Unknown `shapeType` (15 valid values)
`color.invalid_format`	Color isn't `#hex`, `rgb()`, `rgba()`, `hsl()`, or `transparent`
`icon.unknown_id`	Icon ID isn't in the curated 36-icon catalog
`asset.unknown_resource`	Asset layer references a resource ID with no matching `resources[]` entry
`gradient.too_few_stops`	Gradient has fewer than 2 stops
`resource.duplicate_id`	Two resources share an `id`

Each error has a structured path (like layers[3].fontFamily) so your assistant knows exactly which layer to fix. A well-behaved client will retry automatically.

#"Starter kit unavailable"

The list_templates tool returned an error. Two causes:

You're on a local dev build that hasn't published the static starter-design-kit/ folder. Run npm run build once.
The hosted server is having a transient issue. Try curl https://artimic.com/api/mcp/templates directly to confirm.

#Editor doesn't open the .img file

If the editor refuses to load a file your assistant produced:

Verify it's a real .img. The format is a ZIP archive — file the.img should report "Zip archive data".
Check schema version. unzip -p the.img manifest.json | jq .schemaVersion. The current schema is 2. Older versions are auto-migrated, but a far-future version won't load.

Run the validator manually:

curl -X POST https://artimic.com/api/mcp/validate \
  -H 'content-type: application/json' \
  -d "$(unzip -p the.img document.json)"

The response lists errors and warnings exactly as the editor sees them.

#Privacy and data

Each request is stateless — nothing is persisted between calls.
Authentication is per-account via bearer tokens issued at /dashboard/tokens. Treat tokens like passwords — only sha256 is stored server-side; the plaintext is shown to you exactly once on creation. Revoke compromised tokens from the dashboard.
Your design intents and resources transit the endpoint; we don't log payloads, only call counts (for the per-account mcp.call quota — 1000/month on the free plan).