# Troubleshooting

Quick-reference fixes for common issues during Comind.work app development. Each entry shows the symptom, cause, and fix.

## Build and compilation errors[​](#build-and-compilation-errors "Direct link to Build and compilation errors")

### "Cannot find module '@comind/api'"[​](#cannot-find-module-comindapi "Direct link to \"Cannot find module '@comind/api'\"")

* **Cause**: `npm install` not run or `node_modules` missing
* **Fix**: run `npm install` in the project root

### "Cannot use import statement" in actions/logic[​](#cannot-use-import-statement-in-actionslogic "Direct link to \"Cannot use import statement\" in actions/logic")

* **Cause**: importing from `@comind/api/view` in server-side code (or vice versa)
* **Fix**: server code imports from `@comind/api/server`, client code from `@comind/api/view`

### Type error: "as const satisfies ViewLogic" / "as const satisfies ActionLogic"[​](#type-error-as-const-satisfies-viewlogic--as-const-satisfies-actionlogic "Direct link to Type error: \"as const satisfies ViewLogic\" / \"as const satisfies ActionLogic\"")

* **Cause**: using `as const` before `satisfies` - the build rejects this combination
* **Fix**: remove `as const`, keep only `satisfies ViewLogic<typeof entity>`

### Build warning: "Cmw. is deprecated"[​](#build-warning-cmw-is-deprecated "Direct link to Build warning: \"Cmw. is deprecated\"")

* **Cause**: using `Cmw.fieldName` instead of the current API
* **Fix**: replace `Cmw.` with `ComindView` (client-side) or `ComindServer` (server-side)

## Deploy and installation errors[​](#deploy-and-installation-errors "Direct link to Deploy and installation errors")

### "COMIND\_SECRET\_AUTH\_CODE\_MANAGEMENT is not set"[​](#comind_secret_auth_code_management-is-not-set "Direct link to \"COMIND_SECRET_AUTH_CODE_MANAGEMENT is not set\"")

* **Cause**: `.config/dev.env` missing or not in the working directory
* **Fix**: copy from `.config/dev.env.sample` and fill in the API token. If in a git worktree, ensure the config exists in the worktree path.

### "API version mismatch" warnings[​](#api-version-mismatch-warnings "Direct link to \"API version mismatch\" warnings")

* **Cause**: dev environment runs a slightly older platform version than the SDK
* **Fix**: safe to ignore on dev. On production, update the SDK.

### Install succeeds but changes don't appear[​](#install-succeeds-but-changes-dont-appear "Direct link to Install succeeds but changes don't appear")

* **Cause**: app installed to wrong workspace, or browser cache
* **Fix**: check the workspace name in the install command, hard-refresh the browser (`Ctrl+Shift+R`), verify the correct environment (dev vs prod) in `.env`

### "Unauthorized" or "403" on install[​](#unauthorized-or-403-on-install "Direct link to \"Unauthorized\" or \"403\" on install")

* **Cause**: API token expired or wrong environment URL
* **Fix**: regenerate the token in the admin panel, verify `COMIND_BASE_URL` in `.config/dev.env` matches your target

## Runtime issues[​](#runtime-issues "Direct link to Runtime issues")

### Field not showing in the form[​](#field-not-showing-in-the-form "Direct link to Field not showing in the form")

* **Cause**: field not added to layout, hidden by a visibility rule, or wrong field name
* **Fix**: check `views/layouts/default.tsx` has a `<field name="c_yourfield" />` element. Check `views/logic/` for `getInvisibleFields` that might hide it. Verify the field name matches exactly (`c_` prefix).

### Action button not appearing[​](#action-button-not-appearing "Direct link to Action button not appearing")

* **Cause**: precondition returns false, action has `visible: false`, or user lacks permission
* **Fix**: check `actions/logic/preconditions.ts` - the function must return `true` for the current state. Check action options for `visible: false`. Check permission settings.

### Calc field shows stale or wrong value[​](#calc-field-shows-stale-or-wrong-value "Direct link to Calc field shows stale or wrong value")

* **Cause**: `dependsOn` array missing a referenced field, or async calc not yet processed
* **Fix**: ensure `dependsOn` lists ALL `entity.*` fields used in the calc function. For async calcs (rollup, datarollup), values update after a background processing cycle - not instantly.

### Lookup field returns undefined[​](#lookup-field-returns-undefined "Direct link to Lookup field returns undefined")

* **Cause**: using display caption instead of db value, or missing `c_` prefix
* **Fix**: use the db value from the schema (e.g. `"active"` not `"Active"`). Custom fields must use the `c_` prefix.

## CSS and layout issues[​](#css-and-layout-issues "Direct link to CSS and layout issues")

### Form styles flash or re-render on load[​](#form-styles-flash-or-re-render-on-load "Direct link to Form styles flash or re-render on load")

* **Cause**: broad CSS selectors (`font-family` on `body`) conflict with platform CSS that loads later
* **Fix**: scope styles with app-specific class prefixes. Target specific elements instead of `body` or form containers.

### Custom layout HTML not rendering[​](#custom-layout-html-not-rendering "Direct link to Custom layout HTML not rendering")

* **Cause**: missing `ngBindHtml` directive, or UI property not set in `onReady`
* **Fix**: use `ngBindHtml="ui.propertyName"` in layout and set `ComindView.ui.propertyName` in view logic `onReady()`

## Environment issues[​](#environment-issues "Direct link to Environment issues")

### Config file not found in git worktrees[​](#config-file-not-found-in-git-worktrees "Direct link to Config file not found in git worktrees")

* **Cause**: Claude Code or other tools running in a git worktree have a separate working directory
* **Fix**: copy `.config/dev.env` into the worktree, or symlink it

### Claude refuses to edit .env files[​](#claude-refuses-to-edit-env-files "Direct link to Claude refuses to edit .env files")

* **Cause**: Claude Code treats env files as security-sensitive
* **Fix**: approve the file access manually when prompted. Never paste API keys into the chat.

## Getting more help[​](#getting-more-help "Direct link to Getting more help")

* Check [common mistakes](/developer-guide/how-to/common-mistakes.md) for coding pitfalls
* Review the [CLI reference](/developer-guide/reference/cli-reference.md) for command details
* Use `console.log()` in action logic to debug server-side issues (visible in the platform logs)