Troubleshooting
Most problems in IWC surface as a compiler message with a file, line and column. This page collects the ones people meet first, grouped by where they appear. For reading errors, the dev log and writing tests, see Debugging & testing.
Installation
| Symptom | Fix |
|---|---|
iwc: command not found / 'iwc' is not recognized | The install folder isn't on your PATH yet. Open a new terminal. Homebrew puts iwc in $(brew --prefix)/bin, Scoop in ~\scoop\shims, the install script in ~/.iwc/bin (%LOCALAPPDATA%\iwc\bin on Windows). |
! PATH iwc resolves to …, not this binary (from iwc doctor) | Two copies of IWC are installed and an older one comes first on your PATH. Remove it (brew uninstall iwc, scoop uninstall iwc, or delete the old ~/.iwc/bin/iwc and its PATH line), then open a new terminal. A stale binary rejects keys the current version accepts. |
| macOS: "cannot be opened because the developer cannot be verified" | The archive was downloaded with a browser, which quarantines it. Run xattr -d com.apple.quarantine bin/iwc once, or install with Homebrew or the install script instead. |
Starting the dev server
| Symptom | Fix |
|---|---|
! Port 3000 is already occupied (by another application). | Without --port, iwc dev moves to the next free port and prints it. Open the URL it prints. |
Error: Port 3400 is already occupied (by …) | You passed --port and it is in use. The message names the owner and suggests a free port. |
| The same project is already running | iwc dev does not start a second server on the same .iwc/dev.db; it prints the running URL. |
| Pages show data you did not expect, or writes seem to vanish | DATABASE_URL (or the variable in app.iwc database.url) points somewhere else. iwc doctor warns about it. |
Compiler errors
Run iwc check for the full list. Common ones:
| Message | Cause |
|---|---|
unknown key "route" in the top level (data for another tool goes under an x- key, e.g. "x-route") | The key does not exist for this file type — for APIs it is path, not route. Check the file reference. |
the top level is missing required key "path" | A required key is missing. |
"operation" must be one of "db.list", "db.get", … got "database.list" | Use one of the listed values. |
"source" does not apply to text elements (it is used by: image, video, audio, svg, icon) | The property belongs to other element types. See the element reference. |
text elements need "content" or "bind" | Give the text something to show. |
button elements need a "label" | Use label, content, bind or child elements. |
action "open" needs a "target" | open, toggle, scroll and navigate need the id or route to act on. |
"layout" must be an object, got string | In an element, layout is flexbox settings. The page's layout file goes on the screen. |
"justify" must be one of … got "space-between" (did you mean "between"?) | IWC uses between, around, evenly. |
a list data source needs an "item" element to repeat (or use mode "single") | A data-driven container needs item, or "mode": "single" for one record. |
forms submit to POST/PUT/PATCH/DELETE apis; x.api.iwc is GET | Point the form at a write API. |
slot elements only appear inside components | slot is for a component's root. |
stylesheet styles/main.css not found / not-found.ui.iwc not found | app.iwc refers to a file you removed or renamed. |
asset /assets/hero.jpg not found | Asset paths are checked at compile time; add the file under assets/. |
image has no "alt" text (warning) | Describe the image, or use "alt": "" when it is decorative. |
Requests and forms
The dev server logs each request, and under a failed API call, the reason:
text
17:04:26 api POST /api/messages 422 0ms
↳ validation_failed: Some fields are invalid (body is required; email must be a valid email address)| Status | Usual meaning |
|---|---|
401 | The API needs sign-in (security.auth) and the request has no valid session or token. |
403 | Signed in, but without a required role or permission — or a cookie-authenticated write without a valid CSRF token. |
404 on a record you can see in the database | The table's access rules hide it from this user. Someone else's row looks exactly like a missing one. |
409 | A workflow transition from the wrong state, an idempotency key still in progress, or a require step you wrote. |
422 | The body failed the request contract: a missing required field, a wrong type, or an undeclared field. |
429 | A rate limit (security.rateLimit, or sign-in throttling). |
Database and migrations
| Message | Fix |
|---|---|
| A migration that changes a column type, or adds a required field without a default to a table that has rows, is refused | Add a default, make the field optional, or migrate the data deliberately. |
| The database already holds tables IWC did not create | IWC refuses to migrate a database it did not create, so an app pointed at the wrong URL fails before writing. Check the URL; set IWC_ADOPT_DATABASE=1 only to adopt it on purpose. |
Native apps
Run iwc doctor --platform android or --platform ios: it checks the SDK, JDK, Xcode and simulators and prints the fix for each problem. If iwc check reports an element a native target cannot render, either give the element "platforms": ["web"], provide a platform-specific file under platforms/<platform>/, or make the app server-driven. See Android & iOS apps.
Still stuck?
iwc logs -fshows every request and the reason for each failure.iwc check --jsongives diagnostics in machine-readable form.- Limitations lists what IWC does not do yet, so you don't go looking for it.
The Android or iOS app says "Couldn't load this screen"
The app can't reach this project's iwc dev. Start iwc dev first, then iwc dev --android (or --ios) in a second terminal: it finds the port the dev server really uses (3001, 3004… when 3000 is taken by another program) and builds the app for it. A server you set to a real address (a LAN IP for a phone, your domain) is used as written; check that the phone can open it in its browser.
Source: apps/marketing/content/docs/troubleshooting.md