Troubleshooting

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

Build and compilation errors

"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

• 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"

• 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"

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

Deploy and installation errors

"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

• 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

• 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

• 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

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

• 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

• 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

• 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

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

• 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

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

• 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

• Check common mistakes for coding pitfalls
• Review the CLI reference for command details
• Use console.log() in action logic to debug server-side issues (visible in the platform logs)