> ## Documentation Index
> Fetch the complete documentation index at: https://docs.avyratech.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common issues and fixes for the development environment.

# 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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
# 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.

## Database

### Migration failed: enum label "..." already exists

**Symptoms:**

* Running `pnpm db:migrate` fails with a `PostgresError: enum label "..." already exists`.
* This happens when your database state is out of sync with your migration history (e.g., a migration was partially applied or the `__drizzle_migrations` table is missing entries).

**Fix:**
Modify the generated migration file in `packages/db/drizzle/*.sql` to be idempotent for enum additions. Use a `DO` block to check for existing labels before adding them.

```sql theme={null}
DO $$ 
BEGIN 
    IF NOT EXISTS (SELECT 1 FROM pg_enum WHERE enumlabel = 'my_new_label' AND enumtypid = 'public.my_enum_name'::regtype) THEN
        ALTER TYPE "public"."my_enum_name" ADD VALUE 'my_new_label';
    END IF;
END $$;
```

### Missing Migration Files

**Symptoms:**

* `Error: No file ./drizzle/XXXX_filename.sql found in ./drizzle folder`.
* This happens if a migration file referenced in `_journal.json` was deleted.

**Fix:**

1. **Clean Journal:** Open `packages/db/drizzle/meta/_journal.json` and remove the entries for the missing migrations.
2. **Regenerate:** Run `pnpm db:generate`. Drizzle-kit will detect the missing changes and create a new migration.
3. **Migrate:** Run `pnpm db:migrate`. If you hit "label already exists" errors, use the idempotent fix above.

## 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.

```typescript theme={null}
import { slugify } from "@tonnex/utils";
const validSlug = slugify("My Organization Name"); // "my-organization-name"
```