Diagnose and fix common issues in Open Mercato standalone apps. Use when encountering errors, unexpected behavior, modules not loading, widgets not appearing, migrations failing, build errors, or any "it doesn't work" situation. Triggers on "error", "not working", "broken", "fix", "debug", "why isn't", "can't", "fails", "crash", "missing", "404", "500", "module not found", "widget not showing".
Diagnose and fix common issues in Open Mercato standalone apps. Use when encountering errors, unexpected behavior, modules not loading, widgets not appearing, migrations failing, build errors, or any "it doesn't work" situation. Triggers on "error", "not working", "broken", "fix", "debug", "why isn't", "can't", "fails", "crash", "missing", "404", "500", "module not found", "widget not showing".
Troubleshooter
Diagnose and fix common issues in Open Mercato standalone apps. Follow the systematic approach: identify symptoms, check common causes, verify fixes.
Does the user have the required ACL features?
Check setup.ts has defaultRoleFeatures for the user's role.
Fix: Add features to role defaults, re-run setup.
3. Entity & Migration Issues
"Column does not exist" / "Table does not exist"
Symptoms: Database queries fail with missing column/table errors
Checklist:
Did you create a migration after adding/changing the entity?
yarn db:generate # Creates migration file
Fix: Run yarn db:generate to create the migration.
Did you apply the migration?
yarn db:migrate # Applies pending migrations
Fix: Run yarn db:migrate.
Is the migration file correct?
Check src/modules/<module_id>/migrations/ for the latest migration.
Verify it has the expected columns and types.
Fix: If wrong, delete the migration file, fix the entity, and regenerate.
Migration generation creates unexpected changes
Symptoms: yarn db:generate produces migrations for unrelated modules
Checklist:
Are node_modules up to date?
yarn install
Did you modify a core module entity without ejecting?
Never edit node_modules/@open-mercato/*.
Fix: Revert changes to node_modules. Use UMES extensions instead, or eject the module.
Entity changes not reflected
Symptoms: Changed entity file but API still returns old schema
Checklist:
Run yarn generate — entity discovery is cached
Run yarn db:generate — schema needs a migration
Run yarn db:migrate — migration needs to be applied
Restart yarn dev — server caches entity metadata
4. API Route Issues
Route returns 404
Checklist:
Is the file in the correct path?src/modules/<module_id>/api/<method>/<route-path>.ts
Method folders: get/, post/, put/, delete/
API routes without openApi export are not discovered.
Did you run yarn generate?
Route returns 500
Checklist:
Check server logs — look for the actual error message
Is the entity imported correctly? Verify import path
Is organization_id filtering applied? Required for all tenant-scoped queries
Is the zod schema matching the request body? Schema validation errors return 422, not 500
Route returns 401 / 403
Checklist:
Is the user authenticated? Check session/token
Does the user have required features? Check acl.ts + setup.ts role mapping
Are features assigned to the user's role? Check role configuration in admin
5. UI & Widget Issues
Backend page is blank
Checklist:
Does the page have 'use client' directive? Required for pages with interactivity
Check browser console for errors — React rendering errors appear there
Is the correct import path used? Use @open-mercato/ui/backend/...
Are API calls using apiCall / apiCallOrThrow? Never use raw fetch
DataTable shows no data or missing rows
Checklist:
Is the API path correct? Check apiPath prop matches actual API route
Is the entity ID correct? Check entityId prop
Does the API return data? Test with curl or browser devtools
Does the user have view feature? Check ACL
Are pagination props wired? Without page, pageSize, totalCount, and onPageChange, the table only shows the first page with no pagination controls. Check the API returns totalCount in the response.
Is organization_id scoping correct? Records created without proper organization_id won't appear when the API filters by current org
Are records soft-deleted? Records with deletedAt set are filtered out by default
Sidebar icons broken or wrong
Checklist:
Are icons using lucide-react components? Import from lucide-react (e.g., import { Trophy } from 'lucide-react')
AVOID React.createElement('svg', ...) — inline SVG via React.createElement is fragile in bundler contexts and can produce broken icons after yarn generate
Is the icon defined in page.meta.ts? Export as part of metadata.icon
Did you run yarn generate? The generator reads icon metadata from page.meta.ts
Is the widget metadata.id unique? Duplicate IDs cause conflicts
Did you run yarn generate? Widgets are auto-discovered
API Interceptor not running
Checklist:
Is api/interceptors.ts exporting interceptors array?
export { interceptors }
Does targetRoute match? Check exact route path (without /api/ prefix)
Does methods include the HTTP method? e.g., ['GET', 'POST']
Is the interceptor throwing instead of returning { ok: false }?
Errors in interceptors are caught silently
Check priority — lower priority runs first. Another interceptor may be blocking
Component replacement not working
Checklist:
Is widgets/components.ts exporting componentOverrides?
Is the componentId handle correct? Use ComponentReplacementHandles helpers
For replacement mode: is propsSchema provided?
Did you run yarn generate?
8. Database Issues
Connection refused
Checklist:
Is PostgreSQL running?
docker compose ps # Check container status
docker compose up -d # Start if stopped
Is .env configured correctly? Check DATABASE_URL
Is the database created?
yarn initialize # Creates DB + first admin
Query timeout / slow queries
Checklist:
Are indexes present on organization_id and tenant_id? Check entity has @Index()
Is the query filtering by organization_id? Missing filter = full table scan
Are enrichers using batch queries? Missing enrichMany causes N+1
9. Quick Diagnostics
The "Fix Everything" Sequence
When nothing else works, run this full reset sequence:
yarn generate # 1. Regenerate all discovery files
yarn typecheck # 2. Check for type errors
yarn db:generate # 3. Check for pending migrations
yarn db:migrate # 4. Apply any pending migrations
yarn dev # 5. Restart dev server
Common Error → Fix Table
Error Message
Likely Cause
Fix
Module '<id>' not found
Not in src/modules.ts
Add entry, yarn generate
Table '<name>' does not exist
Missing migration
yarn db:generate + yarn db:migrate
Column '<name>' does not exist
Entity changed without migration
yarn db:generate + yarn db:migrate
Cannot find module '@open-mercato/...'
Package not installed
yarn install
Route not found / 404
Missing openApi export or wrong path
Add export, yarn generate
401 Unauthorized
Missing auth or session expired
Check login, check requireAuth
403 Forbidden
User lacks required feature
Check acl.ts + setup.ts roles
422 Unprocessable Entity
Zod validation failed
Check request body matches schema
Widget not showing
Missing injection-table.ts mapping
Add mapping, yarn generate
Enricher data missing
critical: false hiding errors
Set critical: true temporarily
Interceptor not running
Wrong targetRoute or methods
Check exact route path and methods
ECONNREFUSED
Database/service not running
docker compose up -d
DataTable shows fewer rows than expected
Missing pagination props or API totalCount
Wire page/pageSize/totalCount/onPageChange props
Sidebar icons broken or wrong
Inline SVG via React.createElement
Use lucide-react components in page.meta.ts
yarn generate changes unexpected files
Stale generated files
Delete .mercato/generated/, re-run
Rules
ALWAYS run yarn generate as first diagnostic step
ALWAYS check server logs / browser console for actual error messages
NEVER edit files in .mercato/generated/ or node_modules/
NEVER assume the issue — verify with actual error output
Fix the root cause, not the symptom — temporary workarounds become permanent bugs
When suggesting a fix, include the exact command or code change needed
