Common failures and what they mean. Exact app messages are in quotes, so searching the text you see should land you here; the unquoted headings are symptoms.
The client can't reach the server / connection refused
The desktop app isn't running. The MCP server is part of the app — it starts when the app starts and stops when you quit. Open it, then reconnect from your client.
"No project selected. Call list-projects first, then select-project."
Every agent session starts with no project chosen. Tell the agent which project to work in; it will call list-projects and select-project itself. See Connect to MCP.
"app websocket not connected (is the app running?)"
Previews, exports, screenshots and captures are performed by the app itself, not the MCP server. The app was closed mid-request. Reopen it and try again.
"No profile found. Create one first."
Sign in to the app once on this machine, so your profile and projects exist locally.
The app is running but nothing answers on port 16472
Another program already had that port, so the app quietly moved to the next free one. Free 16472 and relaunch, or start the app with MISAKI_HTTP_PORT=16472 to make it take that exact port.
A document or file the agent created isn't visible
One online project maps to a separate local database per profile. Confirm you are signed in as the same profile the agent is working under before concluding the file is missing.
"Email can not be empty."
A required field was left blank. Fill the empty field and submit again.
"Invalid Name"
A project name must be at least two characters, must not start with a number, and may only use letters, numbers, spaces, _ and -. Every space has to come before the first digit — Version final 2 is accepted, Version 2 final is not.
"Project with name '…' Already exists"
Project names must be unique among your own projects. Pick another.
"Profile not found."
The email you tried to invite has no account. The person needs to sign up first.
"Can not invites project your self."
That email is your own account — you already own the project.
"User all ready invited."
That person is already a collaborator on this project.
Imports don't resolve in my app
The generated code depends on the runtime package. Install it: npm install misaki-studio-internal. See Export your code.
My edit to a generated file disappeared
Generated files are overwritten wholesale on every export — that is what keeps the design and the code in agreement. Change the design instead, or wrap the component in a file of your own.
A deleted file's code is still on disk
Export writes but does not prune. Removing a design file leaves its previously generated .tsx and .module.scss behind; delete those by hand.