om-troubleshooter

name: om-troubleshooter description: 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.

Table of Contents

1. Diagnostic Flow
2. Module Issues
3. Entity & Migration Issues
4. API Route Issues
5. UI & Widget Issues
6. Build & Type Issues
7. Extension Issues
8. Database Issues
9. Quick Diagnostics

1. Diagnostic Flow

When the developer reports a problem, follow this order:

Step 1: Identify the Layer

Step 2: Check Generated Files

These commands fix 60%+ of issues, so they are usually the first fix to propose (they are mutating — propose, then run after confirmation per Step 4):

yarn generate          # Regenerate module discovery files
yarn dev               # Restart dev server

If the issue persists after yarn generate, continue to the specific section.

Step 3: Verify the Basics

# Check module is registered
grep '<module_id>' src/modules.ts

# Check generated files exist
ls .mercato/generated/

# Check for TypeScript errors
yarn typecheck

Step 4: Propose Before Fixing

Once you have diagnosed the root cause, do not apply the fix immediately. First present:

1. The root cause — what is actually broken and why.
2. The proposed fix — the exact commands and/or code changes you intend to apply.

Then wait for explicit user confirmation before applying any mutating change. This keeps the developer in control and avoids surprise edits, migrations, or restarts.

Read-only diagnostics may run without asking — they only gather information and change nothing:

When in doubt about whether an action mutates state, treat it as mutating and ask first. Once the user confirms, apply the fix and verify it.

2. Module Issues

Module not found / not loading

Symptoms: 404 on module routes, module not in sidebar, "module not registered" errors

Checklist:

1. Is the module registered in src/modules.ts?

   // Must have this entry:
   { id: '<module_id>', from: '@app' }
   

   Proposed fix: Add the entry and run yarn generate.

2. Did you run yarn generate? Check if .mercato/generated/ contains your module's entries. Proposed fix: Run yarn generate.

3. Is the module folder named correctly? Must be plural, snake_case: src/modules/<module_id>/ Proposed fix: Rename folder to match module ID.

4. Does index.ts export metadata?

   export const metadata: ModuleInfo = { name: '<module_id>', ... }
   

   Proposed fix: Add the metadata export.

5. Is the dev server running with latest changes? Proposed fix: Restart with yarn dev.

Module loads but pages 404

Symptoms: Module appears in generated files but backend pages return 404

Checklist:

1. Are backend page files in the right location?

   • List page: backend/page.tsx (not backend/index.tsx)
   • Detail page: backend/<entities>/[id].tsx (bracket notation) Proposed fix: Rename to match auto-discovery convention.

2. Do pages export metadata with requireAuth?

   export const metadata = { requireAuth: true, features: ['<module_id>.view'] }
   

   Proposed fix: Add metadata export.

3. Does the user have the required ACL features? Check setup.ts has defaultRoleFeatures for the user's role. Proposed 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:

1. Did you create a migration after adding/changing the entity?

   yarn db:generate     # Probes/creates migration file
   

   Proposed fix: Run yarn db:generate to inspect the required migration, then keep only the scoped SQL for your module and update src/modules/<module_id>/migrations/.snapshot-open-mercato.json.

2. Is the entity declared in the right file with the right imports? Entity classes belong in src/modules/<module_id>/data/entities.ts and decorators must come from @mikro-orm/decorators/legacy. Proposed fix: move stale entities/<Entity>.ts patterns into data/entities.ts and fix the imports before regenerating the migration.

3. Did you apply the migration?

   yarn db:migrate      # Applies pending migrations
   

   Proposed fix: Run yarn db:migrate.

4. Is the migration file correct? Check src/modules/<module_id>/migrations/ for the latest migration. Verify it has the expected columns and types. Proposed 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:

1. Are node_modules up to date?

   yarn install
   

2. Did you modify a core module entity without ejecting? Never edit node_modules/@open-mercato/*. Proposed fix: Revert changes to node_modules. Use UMES extensions instead, or eject the module.

3. Is a module snapshot stale? Check whether the generated SQL recreates a table or column that already has a committed migration. Proposed fix: update that module's migrations/.snapshot-open-mercato.json to include the already-migrated schema, then re-run yarn db:generate and expect no changes.

Entity changes not reflected

Symptoms: Changed entity file but API still returns old schema

Checklist:

1. Verify the entity lives in src/modules/<module_id>/data/entities.ts and imports decorators from @mikro-orm/decorators/legacy
2. Run yarn generate — entity discovery is cached
3. Run yarn db:generate — schema needs a migration
4. Run yarn db:migrate — migration needs to be applied
5. Restart yarn dev — server caches entity metadata

4. API Route Issues

Route returns 404

Checklist:

1. Is the file in the correct path? src/modules/<module_id>/api/<method>/<route-path>.ts Method folders: get/, post/, put/, delete/

2. Does it export a default handler?

   export default handler
   

3. Does it export openApi?

   export const openApi = { summary: '...', tags: ['...'] }
   

   API routes without openApi export are not discovered.

4. Did you run yarn generate?

Route returns 500

Checklist:

1. Check server logs — look for the actual error message
2. Is the entity imported correctly? Verify import path
3. Is organization_id filtering applied? Required for all tenant-scoped queries
4. Is the zod schema matching the request body? Schema validation errors return 422, not 500

Route returns 401 / 403

Checklist:

1. Is the user authenticated? Check session/token
2. Does the user have required features? Check acl.ts + setup.ts role mapping
3. Are features assigned to the user's role? Check role configuration in admin

5. UI & Widget Issues

Backend page is blank

Checklist:

1. Does the page have 'use client' directive? Required for pages with interactivity
2. Check browser console for errors — React rendering errors appear there
3. Is the correct import path used? Use @open-mercato/ui/backend/...
4. Are API calls using apiCall / apiCallOrThrow? Never use raw fetch

DataTable shows no data or missing rows

Checklist:

1. Is the API path correct? Check apiPath prop matches actual API route
2. Is the entity ID correct? Check entityId prop
3. Does the API return data? Test with curl or browser devtools
4. Does the user have view feature? Check ACL
5. 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.
6. Is organization_id scoping correct? Records created without proper organization_id won't appear when the API filters by current org
7. Are records soft-deleted? Records with deletedAt set are filtered out by default

Sidebar icons broken or wrong

Checklist:

1. Are icons using lucide-react components? Import from lucide-react (e.g., import { Trophy } from 'lucide-react')
2. AVOID React.createElement('svg', ...) — inline SVG via React.createElement is fragile in bundler contexts and can produce broken icons after yarn generate
3. Is the icon defined in page.meta.ts? Export as part of metadata.icon
4. Did you run yarn generate? The generator reads icon metadata from page.meta.ts

Correct pattern:

// page.meta.ts
import { Trophy } from 'lucide-react'
export const metadata = { icon: <Trophy className="size-4" /> }

CrudForm doesn't save

Checklist:

1. Check browser network tab — look for the POST/PUT request and response
2. Is the zod schema matching the form fields? Mismatched field names cause silent failures
3. Are required fields filled? Check form validation
4. Does the API route handle the HTTP method? Check api/post/ or api/put/ exists

6. Build & Type Issues

yarn build fails

Checklist:

1. Run yarn typecheck first — isolates type errors from build errors
2. Run yarn generate first — regenerates type-dependent files
3. Check import paths — use @open-mercato/<package>/... for framework imports
4. Check for circular imports — module A importing from module B importing from module A

Type errors after adding a module

Checklist:

1. Run yarn generate — updates generated type files
2. Check entity imports — use correct relative or package paths
3. Check zod schema matches entity — types derived from zod must align

"Module not found" in imports

Checklist:

1. Is the package installed? Check package.json dependencies
2. Is the import path correct? Framework packages use @open-mercato/<package>/...
3. Is the package built? Run yarn install to link workspace packages

7. Extension Issues

Response Enricher data not appearing

Checklist:

1. Is data/enrichers.ts exporting enrichers array?

   export const enrichers = [enricher]
   

2. Did you run yarn generate? Enrichers are auto-discovered

3. Is targetEntity correct? Must match the target module's entity ID exactly (e.g., customers.person not customers.people)

4. Is the enricher throwing silently? Check critical: false (default) — errors are swallowed. Temporarily set critical: true to surface errors.

5. Check enricher id is unique — duplicate IDs cause only one to run

Widget not appearing in target module

Checklist:

1. Is the widget mapped in injection-table.ts?

   export const widgetInjections = {
     '<spot-id>': { widgetId: '<your-widget-id>', priority: 50 },
   }
   

2. Is the spot ID correct? Check the exact format:

   • Forms: crud-form:<entityId>:fields
   • Tables: data-table:<tableId>:columns
   • Menus: menu:sidebar:main

3. Does the widget file export default?

   export default widget
   

4. Is the widget metadata.id unique? Duplicate IDs cause conflicts

5. Did you run yarn generate? Widgets are auto-discovered

API Interceptor not running

Checklist:

1. Is api/interceptors.ts exporting interceptors array?

   export { interceptors }
   

2. Does targetRoute match? Check exact route path (without /api/ prefix)

3. Does methods include the HTTP method? e.g., ['GET', 'POST']

4. Is the interceptor throwing instead of returning { ok: false }? Errors in interceptors are caught silently

5. Check priority — lower priority runs first. Another interceptor may be blocking

Component replacement not working

Checklist:

1. Is widgets/components.ts exporting componentOverrides?
2. Is the componentId handle correct? Use ComponentReplacementHandles helpers
3. For replacement mode: is propsSchema provided?
4. Did you run yarn generate?

8. Database Issues

Connection refused

Checklist:

1. Is PostgreSQL running?

   docker compose ps    # Check container status
   docker compose up -d # Start if stopped
   

2. Is .env configured correctly? Check DATABASE_URL

3. Is the database created?

   yarn initialize      # Creates DB + first admin
   

Query timeout / slow queries

Checklist:

1. Are indexes present on organization_id and tenant_id? Check entity has @Index()
2. Is the query filtering by organization_id? Missing filter = full table scan
3. 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

Rules

• ALWAYS present the diagnosed root cause and the proposed fix (commands/code), then wait for explicit user confirmation before applying any mutating change (see Step 4). Only read-only diagnostics may run without asking.
• 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
• Treat yarn generate as the most likely first fix, but propose it before running — it regenerates files and is a mutating action
• Fix the root cause, not the symptom — temporary workarounds become permanent bugs
• When proposing a fix, include the exact command or code change needed