Skip to main content

​
Troubleshooting

​
API

​
Cannot find module ‘dist/main’

If you encounter Error: Cannot find module '.../apps/api/dist/main' when running pnpm dev, it means the API build artifact is missing. This can happen if tsc (TypeScript Compiler) thinks the project is up-to-date (due to incremental builds) but the dist folder was deleted. Fix: We have configured tsconfig.json to store .tsbuildinfo inside the dist folder, so this should not happen automatically. However, if it does, run: 
rm apps/api/tsconfig.tsbuildinfo
pnpm dev

​
Missing Environment Variables

If api fails with missing env vars, it’s because NestJS doesn’t load .env by default without configuration. Fix: We modified apps/api/src/main.ts to explicitly call process.loadEnvFile() (Node.js 20+) during local development. Ensure apps/api/.env exists.

​
General

​
Port EADDRINUSE

If pnpm dev fails with EADDRINUSE, it means a process is already running on the required ports (3000, 3001, 3002). Fix: Kill the process running on the port: 
lsof -ti:3000 | xargs kill -9

​
Missing Environment Variables

If you see errors about missing NEXT_PUBLIC_SUPABASE_URL or SUPABASE_SERVICE_ROLE_KEY, ensure you have .env files in the respective application directories (apps/web and apps/api). Fix: Copy the root .env to the apps: 
cp .env apps/web/.env.local
cp .env apps/api/.env

​
Node.js: —env-file= is not allowed in NODE_OPTIONS

If you encounter node: --env-file= is not allowed in NODE_OPTIONS when running pnpm dev, it means an older configuration or environment variable is trying to pass --env-file via NODE_OPTIONS, which is restricted in newer Node.js/pnpm versions. Fix: Unset NODE_OPTIONS in the script or usage: 
# In package.json script:
"dev": "NODE_OPTIONS='' node --env-file=.env ..."
Or manually unset it before running: unset NODE_OPTIONS && pnpm dev.

​
Shared Packages

​
TS2307: Cannot find module ‘@tonnex/utils’

If you encounter this during a build (especially on Vercel), it’s usually because the TypeScript compiler can’t find the type definitions for the shared package. Fix: We have updated our shared packages (like @tonnex/utils and @tonnex/db) to export their source code (src/index.ts) directly via the exports field in their package.json. This allows the main applications to resolve types and code directly from the source. If you still see this error:
  1. Ensure the package is properly linked: pnpm install
  2. Check that package.json in the respective package points its types and exports to ./src/index.ts.

​
ERR_MODULE_NOT_FOUND or ERR_UNSUPPORTED_DIR_IMPORT

If you encounter this at runtime, it means the application is trying to run the TypeScript source code directly but the runtime environment (Node.js) doesn’t support it. Fix: While development often works via next dev or nest start --watch (which handle TS), production builds should ensure the shared packages are compatible.
  1. Workspaces: Ensure the package is listed as a workspace:* dependency.
  2. Building: Run pnpm build from the root to ensure all packages and apps are built correctly.
  3. Transpilation: For NestJS, we use unplugin-swc to handle TS transpilation of shared packages.

​
Organizations

​
Slug can only contain lowercase letters, numbers, and hyphens

Symptoms:
  • Receiving a 400 Bad Request when trying to create an organization.
  • Error message specifically mentions the slug validation.
Solution: The slug must be URL-friendly. We have implemented auto-slugification in the create-org page. If you are manually editing the slug, ensure it only contains:
  • Lowercase letters (a-z)
  • Numbers (0-9)
  • Hyphens (-)
Spaces and special characters are not allowed. The slugify utility from @tonnex/utils is used to maintain consistency. 
import { slugify } from "@tonnex/utils";
const validSlug = slugify("My Organization Name"); // "my-organization-name"