bknd-debugging

What this skill does

# Debugging Common Issues

Diagnose and fix common Bknd problems using CLI tools, error analysis, and systematic troubleshooting.

## Prerequisites

- Bknd project set up locally
- Terminal/command line access
- Basic understanding of HTTP status codes

## When to Use UI Mode

- Inspecting data in admin panel (`/admin`)
- Verifying entity schema visually
- Testing CRUD operations manually
- Checking user/role configurations

## When to Use Code Mode

- Running debug CLI commands
- Analyzing API response errors
- Checking route registration
- Inspecting configuration paths
- Reviewing server logs

## CLI Debug Commands

### Show All Registered Routes

```bash
npx bknd debug routes
```

Output shows every HTTP endpoint:
- API routes (`/api/data/*`, `/api/auth/*`, `/api/media/*`)
- Admin routes (`/admin/*`)
- Custom Flow HTTP triggers
- Plugin routes

Use when: endpoint returns 404, verifying custom routes registered.

### Show Internal Paths

```bash
npx bknd debug paths
```

Output:
```
[PATHS] {
  rootpath: '/path/to/bknd',
  distPath: '/path/to/dist',
  relativeDistPath: './dist',
  cwd: '/your/project',
  dir: '/path/to/cli',
  resolvedPkg: '/path/to/package.json'
}
```

Use when: config file not loading, path resolution issues.

### CLI Help

```bash
npx bknd --help
npx bknd run --help
npx bknd types --help
```

## HTTP Error Codes

| Code | Meaning | Common Causes |
|------|---------|---------------|
| 400 | Bad Request | Invalid JSON, missing required fields, validation error |
| 401 | Unauthorized | Missing/invalid/expired token |
| 403 | Forbidden | Valid token but insufficient permissions |
| 404 | Not Found | Wrong endpoint, entity doesn't exist, record not found |
| 409 | Conflict | Duplicate unique field, user already exists |
| 413 | Payload Too Large | File upload exceeds `body_max_size` |
| 500 | Server Error | Unhandled exception, database error |

## Common Issues & Solutions

### Config File Not Loading

**Symptoms:** "Config file could not be resolved" error

**Diagnose:**
```bash
# Check config exists
ls bknd.config.*

# Check current directory
pwd

# Check what bknd sees
npx bknd debug paths
```

**Solutions:**
```bash
# Ensure correct extension
mv bknd.config.js bknd.config.ts

# Specify explicitly
npx bknd run -c ./bknd.config.ts

# Check supported extensions: .ts, .js, .mjs, .cjs, .json
```

### Database Not Persisting

**Symptoms:** Data disappears on server restart

**Diagnose:**
```bash
# Check if using memory mode
# Look for "Using in-memory" in startup output
npx bknd run

# Check for database file
ls *.db
```

**Solutions:**
```bash
# Use file-based database
npx bknd run --db-url "file:data.db"

# NOT memory mode
npx bknd run --memory  # Data will be lost!

# Verify in config:
# connection: { url: "file:data.db" }  ✓
# connection: { url: ":memory:" }      ✗
```

### Port Already in Use

**Symptoms:** `EADDRINUSE: address already in use`

**Diagnose:**
```bash
# Find process using port
lsof -i :3000

# Or on Windows
netstat -ano | findstr :3000
```

**Solutions:**
```bash
# Use different port
npx bknd run --port 3001

# Kill existing process
kill -9 <PID>

# Or on Windows
taskkill /PID <PID> /F
```

### Authentication Not Working

**Symptoms:** 401 errors, token not persisting, user always null

**Diagnose:**
```bash
# Test login endpoint
curl -X POST http://localhost:3000/api/auth/password/login \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"password"}'

# Check auth configuration
# Look for "strategy" in response errors
```

**Solutions:**

1. **Auth not enabled:**
```typescript
export default {
  app: {
    auth: { enabled: true },  // Required!
  }
}
```

2. **Wrong strategy path:**
```bash
# Password auth endpoint:
POST /api/auth/password/login    # ✓
POST /api/auth/login             # ✗ 404
```

3. **JWT secret not set (production):**
```typescript
auth: {
  jwt: {
    secret: process.env.JWT_SECRET,  // Required for production
  }
}
```

4. **Cookie not set (CORS):**
```typescript
auth: {
  cookie: {
    secure: false,     // Set true only for HTTPS
    sameSite: "lax",   // Not "strict" for OAuth
  }
}
```

5. **Token not persisting (frontend):**
```typescript
const api = new Api({
  host: "http://localhost:3000",
  storage: localStorage,  // Required for token persistence
});
```

### Permission Denied (403)

**Symptoms:** Valid token but 403 Forbidden

**Diagnose:**
```bash
# Check user's role
curl http://localhost:3000/api/auth/me \
  -H "Authorization: Bearer <token>"

# Check role permissions in config
```

**Solutions:**

1. **Guard not enabled:**
```typescript
export default {
  app: {
    auth: {
      guard: { enabled: true },  // Required for permissions
    }
  }
}
```

2. **No default role (anonymous access):**
```typescript
auth: {
  guard: {
    roles: {
      anonymous: {
        is_default: true,  // Allow unauthenticated access
        permissions: ["data.entity.read"],
      }
    }
  }
}
```

3. **Role missing permission:**
```typescript
roles: {
  user: {
    permissions: [
      "data.entity.read",
      "data.entity.create",  // Add if needed
    ]
  }
}
```

4. **Entity-specific permission needed:**
```typescript
permissions: [
  { permission: "data.entity.read", entity: "posts" },
]
```

### Entity/Record Not Found (404)

**Symptoms:** 404 on data endpoints

**Diagnose:**
```bash
# List all entities
curl http://localhost:3000/api/data

# Check entity name (case-sensitive)
curl http://localhost:3000/api/data/Posts    # ✗
curl http://localhost:3000/api/data/posts    # ✓

# Verify routes
npx bknd debug routes | grep data
```

**Solutions:**

1. **Schema not synced:**
```bash
# Restart server to sync schema
npx bknd run
```

2. **Entity name case mismatch:**
```typescript
// Schema defines lowercase
entity("posts", { ... })

// API call must match exactly
api.data.readMany("posts");     // ✓
api.data.readMany("Posts");     // ✗ 404
```

3. **Record doesn't exist:**
```typescript
const result = await api.data.readOne("posts", 999);
if (!result.ok) {
  console.log("Not found:", result.status);  // 404
}
```

### Type Errors with em()

**Symptoms:** TypeScript errors using schema object

**Problem:** `em()` returns schema definition, NOT queryable EntityManager.

```typescript
// WRONG - this will fail
const schema = em({
  posts: entity("posts", { title: text() }),
});
schema.repo("posts").find();  // ✗ Error!

// CORRECT - use SDK for queries
const api = new Api({ url: "http://localhost:3000" });
await api.data.readMany("posts");  // ✓
```

For direct database access (server-side only):
```typescript
const app = new App(config);
await app.build();
const posts = await app.em.repo("posts").findMany();  // ✓
```

### Schema Sync Issues

**Symptoms:** Entity exists in code but not in database, or vice versa

**Diagnose:**
```bash
# Check admin panel -> Schema view
# Or query directly
curl http://localhost:3000/api/system/schema
```

**Solutions:**

1. **Restart server** - schema syncs on startup:
```bash
npx bknd run
```

2. **Force sync** (may drop data):
```typescript
options: {
  sync: {
    force: true,  // Dangerous! Can drop tables
  }
}
```

3. **Check mode** - Database Mode ignores code schema:
```typescript
// Code Mode (default) - schema from code
mode: "code"

// Hybrid Mode - merges code + database
mode: "hybrid"
```

### File Upload Failing

**Symptoms:** 413 error, upload silently fails

**Diagnose:**
```bash
# Check file size
ls -la myfile.jpg

# Test upload
curl -X POST http://localhost:3000/api/media/upload \
  -H "Authorization: Bearer <token>" \
  -F "[email protected]"
```

**Solutions:**

1. **File too large:**
```typescript
media: {
  body_max_size: 10 * 1024 * 1024,  // 10MB
}
```

2. **Storage not configured:**
```typescript
media: {
  adapter: {
    type: "s3",
    // ... S3 config
  }
}
```

3. **Local storage (dev only):**
```typescript
import { registerLocalMediaAdapter } from "bknd/adapter/node";
const local = registerLocalMediaA