Common Issues and Troubleshooting

TL;DR (Top 10 Quick Reference)

1. .env.local missing or DATABASE_URL not filled → Copy template and fill connection string
2. Prisma generation failed → bunx prisma generate then init
3. Port occupied → PORT=3001 bun dev
4. Login 403/404 → Action prefix incorrect or role not bound to permission
5. Menu not showing → Menu path doesn't match page route
6. List empty → fieldsConfig key doesn't match database field
7. Form fields not showing → Hidden/disabled or type not supported
8. Batch operations invalid → Corresponding actions not provided or switch not enabled
9. next build reports ESLint/TS → Fix type/syntax issues first
10. External image 403 → Use regular img (this project already handles it)

Troubleshoot in order: startup → database → permissions → components → build, covering basic dependencies and environment variables first.

Startup Failure / Dependency Issues

• Confirm Node.js 20.9+, reinstall dependencies with bun install or pnpm install using local package manager.
• Check if .env.local exists and is read by bun run init; missing DATABASE_URL will directly abort.
• Port occupied: Default 3000, use PORT=3001 bun dev when conflicted.
• macOS/Linux no execution permission: Add chmod +x scripts/*.sh to scripts.

Database / Prisma

• Connection error: Verify connection with psql $DATABASE_URL or bun prisma db push, cloud databases need public access/whitelist.
• Migration failed: Delete .prisma cache, re-run bun prisma generate, then execute bun run init; if schema changed, clean history migrations or rebuild database first.
• Seed data missing: Confirm bun run init completed all 4 steps; if only want to import seeds, execute bun run seed (need to generate Prisma Client first).

Login / Permissions / Menu

• Admin login redirect failed: Check BETTER_AUTH_URL matches actual access domain (including protocol port), BETTER_AUTH_SECRET at least 32 bytes.
• 403/404: Confirm Action name prefix is sys, and bind corresponding permissions and menus in roles; RBAC missing permissions will directly return 404.
• Menu not showing: menu.path needs to match actual page route; if external link or custom page, keep unique path and check associated permission code.

SmartCrudPage / SmartForm

• List empty or error: key in fieldsConfig must match database field; functions like actions.getList need to be fully passed in.
• Form fields not rendering: Check if form.hidden/form.disabled is configured, or field type not supported (refer to /docs/api/FIELDS_CONFIG).
• Batch operations/custom buttons invalid: Confirm corresponding handler functions provided in actions, and enable switches like enableBatchActions on component.

Build / Runtime

• next build error: Prioritize checking unresolved TypeScript/ESLint issues; MDX errors usually are incorrect import paths or unsupported syntax.
• Static resources 404: Ensure files are in public/ and reference paths start with /; cloud storage settings need complete configuration in .env.local (see /docs/admin/guides/STORAGE).
• i18n routing issues: Include locale in access path (e.g., /zh/admin), and check default language settings in i18n/config.

Still Not Resolved?

• Locate by module: Database related check /docs/admin/database/PRISMA_GUIDE; permission issues combine /docs/architecture/PERMISSION_MODEL with /docs/admin/rbac/CONFIGURATION.
• When submitting Issue, include: execution command, complete terminal error, key .env.local configuration (masked), Prisma version and database type.